API Credentials is the new OAuth 2.0 way to secure access to the public API. The legacy API Key remains a robust mechanism but provides access to all API endpoints without any capability to disable access to an endpoint.

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.

The legacy API Key is still supported, but is being deprecated and API Credentials is the recommended security feature to use. However, v1 of the API does not support API Credentials and so API keys must be used.

A major change between using that API Credential and the legacy API Key is that the legacy API Key is itself the bearer token, with no expiration lifespan, and can be used as is. On the other hand, API Credentials are an Id/Secret pair and are used to acquire the bearer token. This acquired bearer token is actually a JWT, and has a finite lifespan, currently 24 hours and needs to be reacquired periodically.

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'.
3. Click on 'Create API 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"
}

API Keys are the legacy method of providing access to the public API. We recommend using API credentials if possible.

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'.
3. Click the link on the banner to go to the legacy API page.
4. Click the purple 'Generate' button and your new API key will appear
   
5. To use it in a request, attach it to requests as a header using the format - Authorization: Bearer API_KEY

API keys do not expire, but if you do need to generate a new key, you can click the 'Revert' button on the legacy API page, which will revoke the previous key and allow you to generate a new one.

More information is available within the app here.