API Tokens

An API token, also called an access token, is a credential used to authenticate a client when making API requests. It is issued by an authorization server operated by Flute.

To obtain an API token, the client makes a call to this authorization server using their API key credentials of their client id and client secret. After successfully authenticating, an API token is returned. The API token is encrypted and means it is safe to expose in frontend code. The API token must be included with API requests to authorize access to protected resources. Because Flute considers all API endpoints and resources to be protected, an API token is required for every API request.

Flute uses two types of API keys: Partner and merchant.
These token types correspond to the type of API key used to obtain them. See the API Keys page for more details.

API tokens are obtained using the OAuth 2.0 client credentials grant.

There is no indication which type of API key it is. Care must be taken tracking an API key. We recommend using API key names that include Partner or Merchant.

A partner API token is issued using a partner API key.

A partner is an organization that manages one or more merchants assigned to it. An API key issued to a partner is called a partner API key. An API token obtained from partner API key is called a partner API token.

Partner API tokens are intended only for partner API endpoints. They cannot be used to access merchant API endpoints. Endpoint documentation will state if a partner API token must be used for that call.

A merchant API token is issued using a merchant API key.

A merchant is a business entity that can also be assigned to a partner. An API key issued to a merchant is called a merchant API key. An API token obtained from merchant API key is called a merchant API token.

Merchant API tokens are intended only for merchant API endpoints. They are not interchangeable with other merchant's API tokens. They are specific to the merchant for which they were issued and cannot be used to access resources belonging to another merchant, even if both merchants are assigned to the same partner.

Each API token has a limited lifetime, also known as an expiration period. The expiration period is 900 seconds (15 minutes). This value is returned in the API token request in the response field expires_in.

A successful request returns the API token information in the response body:

{
  "access_token": "u7BYwJx26U1lT...TZpKvndLCC4",
  "expires_in": 900,
  "refresh_token": "def50200newrefresh123456789",
  "token_type": "Bearer"
}

When the API token expires, it must be obtained again or refreshed. A refresh method is available to transparently obtain a new, valid API token.

The application must support API token renewal. For programming requirements, see Coding for API tokens below.

Each API token includes the ability to refresh itself. This allows clients to obtain a new API token without having to re-authenticate or to sign in multiple times during a session.

A refresh token is returned in the API token request in the response field refresh_token. In the example above, the refresh_token is def50200newrefresh123456789. The expiration period is six hours.

This refresh token is used to exchange the current or expired API token with a new one. A call is made to authorization server using the refresh token's value.

The application must support API token renewal. For programming requirements, see Coding for API tokens below.

To obtain a refreshed API token, see Refreshing an API Token section below.

API tokens can be obtained whenever needed. Common cases to obtaining a new API token are:

• The client signs in.
• The current one expired.

Always protect the API key credentials of the client ID and the client secret. Keep the client secret as a password. Never expose the client secret in client-side code or public repositories. If you suspect the client secret has been compromised, revoke the owning API key and create a new one.

The host application, that is, your integration, must provide the logic to manage API tokens. The authorization server issues the tokens, but it does not automatically refresh them for the client.

Typically, the application implements the following in their workflow:

1. Obtain the API tokens, both the API token and refresh token.
2. Store both new access and refresh token tokens securely. Both may be used frequently.
3. Include the API token in the Authorization: Bearer header of API requests.
4. For managing valid API tokens, do one or more of the following:
   1. Detect a 401 Unauthorized response. Check the reason for the response ensuring it's from an expired API token.
   2. For any other reason to refresh or even revoke the token. Token refresh is a client-side responsibility. The Flute API doesn't push a new access token to the client. The client must request one when necessary.
5. Retry the original API request if appropriate.

Many languages provide OAuth client libraries that handle much of this automatically. However, the application still needs to:

• Store the tokens.
• Configure the OAuth client.
• Handle refresh failures (for example, if the refresh token has expired or been revoked).

After creating the API token, include it in the Authorization header of your API requests to authenticate and authorize access to the Flute API endpoints.

     Authorization: Bearer <API_TOKEN>

The following example calls the transactions endpoint with a token:

curl 'https://sandbox.api.flute.com/v2/transactions' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Accept: application/json'

An API token is obtained for the environment it will be used in. There are two Flute environments: Sandbox and production.

API tokens are not interchangeable between the two environments. That is, an API token obtained for one environment cannot be used with the other.

Partner and merchant API keys may be used to obtain API tokens from either environment.

The following endpoints are used to obtain an API token. Use the relevant URL for the intended environment.

Note the order of the labels in the sandbox host. It is sandbox.oauth.api.flute.com, with sandbox first, not oauth.sandbox.api.flute.com.

Send a POST request to the token endpoint for your environment. Supply the client ID and client secret from your API key, and request the client_credentials grant. For instance, this example obtains an API token for the sandbox environment.

curl -X 'POST' 'https://sandbox.oauth.api.flute.com/oauth2/token' \
-u '<CLIENT_ID>:<CLIENT_SECRET>' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=offline_access'

A successful request returns the tokens in the response body:

{
  "access_token": "u7BYwJx26U1lT...TZpKvndLCC4",
  "refresh_token": "def50200newrefresh123456789",
  "token_type": "Bearer",
  "expires_in": 900
}

The expires_in value is the lifetime of the access_token in seconds.

In the example, the API token expires after 900 seconds (15 minutes).

An expired or otherwise invalid API token typically results in a 401 Unauthorized response. If the API token has expired, or, as best practice, is near to expiring, a new API token may be obtained.
See the Refreshing an API Token section for details.

An API token can be refreshed before or after it expires by using the refresh token returned when the current API token was first obtained. Refreshing an API token automatically revokes the current API token. Therefore, do not explicitly revoke the current API token just because of a refresh.

The following endpoints are used to refresh an API token. These are the same endpoints used to obtain an API token except the body parameter refresh_token is used.

The following request refreshes an API token. Use the relevant URL above for the intended environment.

Send a POST request to the token endpoint for your environment. Include the refresh token returned when the API token was obtained, and request the refresh_token grant. For instance, this example obtains a new API token for the sandbox environment.

curl -X 'POST' 'https://sandbox.oauth.api.flute.com/oauth2/token' \
-u '<CLIENT_ID>:<CLIENT_SECRET>' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=refresh_token \
-d 'refresh_token=<REFRESH_TOKEN>'

A successful request returns a new API token in the response body:

{
  "access_token": "eyJhbGciOi...newAccessToken",
  "refresh_token": "def50200newRefreshToken123456789",
  "token_type": "Bearer",
  "expires_in": 900
}

The returned new values completely replace the existing ones. This includes the refresh token. If the API token needs to be refreshed later, use the most recently returned refresh token. Store the new values in the application for subsequent API requests.

An API token may be revoked and prevented from being used again. Reasons include when a client signs out, it is suspected of being compromised, or the application no longer needs access, such as being uninstalled or decommissioned.

Refreshing an API token automatically revokes the current API token. Therefore, do not explicitly revoke the current API token just because of a refresh.

To revoke or delete a current API token, delete the owning API key. This may be done:

• Manually through the Flute dashboard for either the partner or merchant.
• Programmatically for merchant API keys. The merchant's partner uses DELETE /pay-api/v{{version}}/merchants/tokens/{{clientId}}.

For the full request and response reference, including every error response, see API Tokens.