An API token is required for each endpoint use. An API token can only be created after an account is created, registered, and at least one API key has been created.

The API token is an authorization token needed for each for endpoint. It is an encrypted string that combines the client Id and client secret from an API key (created earlier). It contains authentication and authorization coding. This includes any privileges the user or account affords. Being encrypted means the API token is safe to expose in frontend code. The API token is time-sensitive and expires after an amount of time.

It may be created as needed. We recommend generating a new API token before each endpoint use. This ensures the API token will be valid for each call.

The API token is an OAuth 2.0 Client Credentials authorization flow. The Client Credentials Flow is an OAuth 2.0 authorization Bearer grant. This means a server-side application obtains an access token using its client credentials (client ID and client secret) to protect resources.

Generating the API Token

Sandbox
Use the sandbox environment for development and testing. No payments, charges, or invoices will be enforced.
Endpoint: POST https://sandbox.oauth.api.flute.com/oauth2/token

Production
Use the production environment for deploying the payment system live to clients. All payments, charges, or invoices will be enforced.
Endpoint: POST https://oauth.api.flute.com/oauth2/token

The sandbox and production environments API tokens use the same API key and differentiated only by the environment endpoint. The two API tokens types are not interchangeable and cannot be used in an environment different than they were created for.

The API key that was created in the initial account registration is needed to create an API token. The client ID and client secret are used together to create an API token.

The following is an example of the complete request for the sandbox environment:

curl -X 'POST' 'https://sandbox.oauth.api.flute.com/oauth2/token' \
-u '594838709594...38697242c:9eb2c6859daa4...d8ae5da9' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=offline_access'

The following example is passed back in the response body:

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

Using the API Token

The token endpoint returns both an access_token and a refresh_token. The lifespan of the access_token is indicated by the expires_in value. The lifespan of the refresh_token is set by OAuth standards.

Clients are encouraged to use either token as needed. For example, it may be easier to call for a new access_token before each user-initiated action. The access_token may also be left to expire, and then use refresh_token procedures to continue. For example, mobile phones apps may need to use the refresh_token to avoid consistently signing back in.

In the endpoint header, use the following access_token format:

"Authorization": "Bearer u7BYwJx26U1lT...TZpKvndLCC4"

The following example creates a new access token:

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

As a reminder, always secure your client ID and especially your client secret. Never expose the client secret in client-side code or public repositories. It should be kept private and secure. If it is suspected that the client secret has been compromised, the owning API key must be deleted. A new API key can then be created.

Error Responses

If authentication fails, the token endpoint returns an error. The following are commonly encountered errors.