Authorization

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.

Base authorization URLs

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

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

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

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 obtaining an API token 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 is an example of refreshing an API token 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=refresh_token&refresh_token=def50200newrefresh123456789'

Regardless of either obtaining or refreshing an API token, the following example is passed back in the response body:

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

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.

HTTP Status	Common Cause
400 Bad Request	Missing or invalid grant_type, or malformed request body.
401 Unauthorized	The API token has likely expired. Create a new one and retry the request.

Operations

Obtains or refreshes an API token

Request

POST {{baseOAuthURL}}/oauth2/token

This endpoint obtains or refreshes an API token.

The resulting API token may be either a:

Merchant token if it is created from a merchant API key
Partner token if it is created from a partner API key

For making an endpoint call, the two token types are neither the same nor interchangeable. The endpoint description specifies the required API key type. By default, a merchant API key is required.

Obtaining a new API token or refreshing an existing one uses the same endpoint. However, body fields are different:

Obtaining a new API token uses:
- grant_type = client_credentials
- scope = offline_access
Refreshing an existing API token uses:
- grant_type = refresh_token
- adds the refresh token
- does not use scope

The examples below illustrate these request body fields. The differences are in bold.

Obtain token
Set the body type to `x-www-form-urlencoded`.

Body fields:
grant_type = client_credentials
scope = offline_access
client_id = u0LJUTc...BKhM3L
client_secret = eyJhbG...d7iXs

Refresh token
Set the body type to `x-www-form-urlencoded`.

Body fields:
grant_type = refresh_token
refresh_token = YhjQpM...EVkVuB
~~scope = offline_access~~
client_id = u0LJUTc...BKhM3L-y
client_secret = eyJhbG...d7iXs

Security

Bearer

Bodyapplication/x-www-form-urlencodedrequired

client_idstringrequired

Specifies client ID from the API key for the account.

Example: 59483870959438697242c

Example:"59483870959438697242c"

client_secretstringrequired

Specifies the client secret from the API key for the account.

Example: 9eb2c6859daa4d8ae5da02a9

Example:"9eb2c6859daa4d8ae5da02a9"

grant_typestringrequired

Specifies the literal value client_credentials.

If obtaining an API token, use: `client_credentials`
If refreshing an API token, use: `refresh_token`

Example: client_credentials

Example:"client_credentials"

scopestringrequired

Specifies the literal value offline_access.

Use only for obtaining an API token.
Omit when refreshing an API token.

Example: offline_access

Example:"offline_access"

curl -i -X POST \
  https://developer.flute.com/_mock/api-reference/oauth2/token \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=59483870959438697242c \
  -d client_secret=9eb2c6859daa4d8ae5da02a9 \
  -d grant_type=client_credentials \
  -d scope=offline_access

Responses

OK. Access token issued successfully.

Bodyapplication/json

access_tokenstringrequired

Indicates the API token.

Example: 213bf7a8-9b0c-4d1e-2f3a-4b5c6d7e8f14

Example:"213bf7a8-9b0c-4d1e-2f3a-4b5c6d7e8f14"

token_typestringrequired

Indicates the token type.

Example: Bearer

Example:"Bearer"

expires_ininteger

Indicates the expiry, or lifetime, (in seconds) of the API token.

Example: 900

Example:900

refresh_tokenstring

Indicates the refresh token (only for authorization_code grant).

Example: 324c08b9-0c1d-4e2f-3a4b-5c6d7e8f9a25

Example:"324c08b9-0c1d-4e2f-3a4b-5c6d7e8f9a25"

scopestring

Indicates the granted scopes, space-delimited.

Example: null

Example:null

Response

{
  "access_token": "213bf7a8-9b0c-4d1e-2f3a-4b5c6d7e8f14",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "324c08b9-0c1d-4e2f-3a4b-5c6d7e8f9a25",
  "scope": null
}