First Orion API Authentication

We have two methods of generating the required Authorization Token needed for API requests.

1. OAuth 2.0
2. In-house authentication service (Original Service)

To generate API credentials, register your business in the First Orion Customer Portal for a Annual Contract Agreement (Post paid).

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.

OAuth 2.0

This method uses standard OAuth 2.0 practices to generate the Authentication token.

There are two ways to generate the Authorization token:

1. Using api credentials with the --user tag in the header
   1. Replace 'apikey:secretkey' with user generated credentials

curl --location 'https://api.firstorion.com/v2/auth' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user 'apikey:secretkey' \
--data-urlencode 'grant_type=client_credentials'

{
    "access_token": "your_token",
    "expires_in": 3600,
    "token_type": "Bearer"
}

2. Using a base64 encoded API Key and Secret Key
   1. Replace 'apikey:secretkey' with base64 encoded string generated from the credentials.

curl --request POST \
--url https://api.firstorion.com/v2/auth \
--header 'accept: application/json' \
--header 'authorization: Basic apikey:secretkey' \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials

{
    "access_token": "your_token",
    "expires_in": 3600,
    "token_type": "Bearer"
}

In-house authentication service

Original 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.

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
}

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.