API Credentials represent the new OAuth 2.0 approach for securing access to public API endpoints at Flexport. While API Keys remain a reliable method, they grant access to all API endpoints without the ability to selectively disable access to specific endpoints.

The new API Credential mechanism allows clients to generate credentials to access only endpoints which are required. This provides a safeguard capability when access keys are shared both within the organization and with 3rd parties. Bearers of these credentials can only access endpoints they have permissions to and no more.

v1 of the API does not support API Credentials and API keys must be used.

API Keys serve as bearer tokens, whereas API Credentials consist of an Id/Secret pair used to obtain the bearer token. The bearer token, which is a JWT, has a finite lifespan of 24 hours and requires periodic reacquisition. There is a daily limit on the number of token requests allowed, capped at 10 requests per day.

An active client app account.

1. Click on ‘Your Business’ from the top navigation bar and choose Settings.
2. Under Settings go to the tab 'API Credentials'.
3. Click on 'Create Credentials'.
4. Select the appropriate resources and enable them for access. Click on Create. Note that the resources that aren’t checked will have access restrictions.
5. On successful creation, a new row will be displayed. Copy the Client ID and Client Secret by clicking on the copy icon.

Use the Client ID and Secret to retrieve an Access Token by following the steps below:

Endpoint: https://api.flexport.com/oauth/token
Parameters: client_id, client_secret, audience=https://api.flexport.com, and grant_type=client_credentials
Request Type: POST

1. Make a POST request to the above endpoint.
2. From the json response body, extract the access_token which is used in subsequent calls.

Example Curl Command to make a POST request to /oauth/token endpoint:

curl -X "POST" "https://api.flexport.com/oauth/token" \
  -H "Content-Type: application/json"\
  -d $ '{
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "audience":"https://api.flexport.com",
    "grant_type":"client_credentials"
  }'

1. Once the Access token is fetched from the response, attach it to requests using the format - Authorization: Bearer ACCESS_TOKEN
2. Cache and reuse this token until expiration. Do not acquire the Access token for each API request.
3. The Access token is a JWT and the expiration timestamp can be fetched by decoding the JWT and accessing the field “exp” (unix timestamp). The following is an example of a decoded JWT:

{
  "iss": "https://api-prod.identity.flexport.com/",
  "sub": "aFk49maTssoafvF38V0ZH6Hkg7WOnzIO@clients",
  "aud": "https://api.flexport.com",
  "iat": 1637616778,
  "exp": 1637703178,
  "azp": "aFk49maTssoafvF38V0ZH6Gkg7QOnzIO",
  "gty": "client-credentials"
}

To create an API key, you will need an active client app account. The process is similar to creating API credentials.

1. Click on ‘Your Business’ from the top navigation bar and choose Settings.
2. Under Settings go to the tab 'API Keys'.
3. Click on 'Create Key'.
4. On successful creation, a new row will be displayed. Copy the token by clicking on the copy icon.
5. To use it in a request, attach it to requests as a header using the format - Authorization: Bearer API_KEY

API Keys are initially set to expire upon creation, but you have the flexibility to revoke them instantly by simply pressing the revoke button.

More information is available within the app here.