Getting started

Understanding the tutorials

All request examples in our documentation use cURL notation.

You can refer to the API Reference for the complete OpenAPI specification.

All Global Relay API endpoints require HTTPS and conform to HTTP/1.1. Because the Event Archiving API is HTTP-based, it works with any language that has an HTTP library.

Enrolling your application

Before you can start calling the Event Archiving API, you must register your application and specify the data types you plan to archive. For more information about this process, contact your Global Relay Implementation engineer.

Authenticating your requests

As part of the enrollment process, you receive an email from your Global Relay Implementation Specialist with a link to your secret API credentials, which must be kept secure and private. You will use this client credential in your authorization request to retrieve you access token. Never store these credentials in a code repository or include them in client-side code..

All Global Relay APIs require an access token to authenticate and authorize incoming requests.

To retrieve an access token from the /oauth2/token endpoint using your client credentials, make the following POST request:

curl -X POST "https://iam-oauth2.globalrelay.com/oauth2/token" \
 -H "Authorization: Basic <CREDENTIALS>" \
 -d "grant_type=client_credentials" \
 -d "scope=openid eventfeed file write"

We require that you send your client credentials in the Authorization header using the Basic Authentication scheme, as shown in the example. You do not need to transform or encode the supplied credentials in any way.

To use the Event Archiving API, you must request a token with the scopes “openid”, “eventfeed” and “write”. If you also require use of the /files endpoint for sending file attachments, you must also request the “file” scope.

You will receive the following response payload:

{
    "access_token": "<YOUR_ACCESS_TOKEN>",
    "expires_in": "<EXPIRY_TIME>",
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "scope": "openid eventfeed file write",
    "not-before-policy": 0
}

In each request to the Event Archiving API endpoint, pass the following items in the HTTP header:

• Access token that corresponds to the data type being sent in the “Authorization: Bearer” field
• Data subtype for which your company has been provisioned in the “x-subtype” field

curl -X POST “https://eventfeed.api.globalrelay.com/v2/oc-event” \
-H “Authorization: Bearer <YOUR_ACCESS_TOKEN>” \
-H “x-subtype: <SUBTYPE>”

Handling token expiry

The access token you fetch should be reused, and a new one should only be requested when the current token expires. The API returns a 403 error response for expired access tokens.

To obtain a new access token, make a new request to the /oauth2/token endpoint.

Revoking compromised credentials

Secure your client credentials with the same level of robustness as you would for usernames and passwords. If you suspect they are compromised, contact Global Relay as soon as possible to get them revoked and replaced.

Rate limits

API calls are limited to 1000 requests per minute, per client, for the /oc-event endpoint, and 100 per minute for the /files endpoint. If your rate limit is reached, the API will return with a 503 Service Unavailable error. Refer to the API Reference for more details.

There is no limit to the amount of data you can send, but Global Relay may batch the data into separate messages in your Archive. For more information, contact your Global Relay Implementation engineer.