First Orion API Authentication

The Branded Communication API is built using a separate, in-house authentication service.

The basic pattern is:

1. Acquire an Authorization token using the API Key and Secret Key
2. Add the JSON Web Token (JWT) to each API request as an Authorization header

The token is valid for 60 minutes, after which a new token must be acquired using a refresh_token which is provided when the initial Authorization token is issued.

It is highly recommended that a client application builds logic on the authentication and re-authentication flows that allow retries in case the first attempt to renew the Authorization token fails. This can easily be achieved by attempting to refresh the Authorization token 10 minutes before it is set to expire and retry once every minute until it is successfully renewed. The renewal is expected to be successful on the first attempt - the retry logic is only to have sufficient resiliency against exceptions.

To generate API credentials, register your post-paid business in the First Orion Customer Portal.

Tokens are pre-signed and cannot be revoked; however, API keys can be managed directly in the Customer Portal by Business Admin users or via the First Orion Business API Keys endpoints. Once the token reaches expiration, it can no longer be used.

Generate First Orion API Keys

1. In the First Orion Portal navigate to the API Keys section on the left hand side.
2. Click Generate Key to generate the new key.
3. Copy and save or download the generated keys.

Here's an example cURL request. Replace the API Key and Secret Key in the headers.

curl --location --request POST 'https://api.firstorion.com/v1/auth' \
--header 'X-SERVICE: auth' \
--header 'content-type: application/json' \
--header 'X-API-KEY: api_key_here' \
--header 'X-SECRET-KEY: secret_key_here'

{
    "token": "your_token",
    "refresh_token": "your_refresh_token",
    "expires_in": 3600,
    "token_type": "Bearer",
    "expires_at": 1754509170
}