# Obtains or refreshes an API token

POST {{authBaseURL}}/oauth2/token
This endpoint obtains or refreshes an API token.
Each Flute endpoint (with the exception of this authentication endpoint) requires an API token, also called an access token).
It is an encrypted string generated from a Flute-owned authentication server.
The API token is a combination of an authentication of the user and an authorization of the user's permissions.
Each API token has a limited lifespan.
This is often 900 seconds, or 15 minutes although the actual value is returned by the authentication call.
After the API token expires, it can no longer be used to make calls.
The API token must then be obtained anew or refreshed.
### Obtaining API Tokens
There are two ways to get a valid API token: **Obtaining a new token** or **Refreshing an existing token**.
The endpoint for obtaining a new API token or to refresh an existing one is the same.
Only the request body fields are different.
Selecting the appropriate option displays the relevant fields and information.
**Obtaining a new token**
A new token must be obtained because:
* No token exists.
This may be from the user just logging in or the previous API token expired.
* The stored `refresh_token` expired, has been revoked, or gets rejected by the server (such as a refresh attempt failed).
* A different API key is being used.

To obtain a new API token, see the call below, selecting **Obtain a new token**.
This displays the fields and details needed to make the call.
**Refreshing an existing token**
An existing API token may be refreshed to create a new, valid API token.
That existing API token may be currently valid or has expired recently.
The goal is to provide continuous operation.
This allows users to remain authenticated without repeating full credential authentication on every renewal.
An API token may be refreshed because:
* The current `access_token` is about to or has already expired.
* A valid `refresh_token` is currently available and valid from the most recent API token.

To refresh an API token, see the call below, selecting **Refresh an existing token**.
This displays the fields and details needed to make the call.
### API Token Types
API token types depend on the type of API keys used to create them.
The resulting API token type will be one of following:
* Merchant token if it is created from a merchant API key.
* Partner token if it is created from a partner API key.

The two API keys types are not interchangeable.
Most Flute endpoints require a merchant token.
The endpoint description specifies the required API key type.
Endpoints requiring a partner token will be explicitly marked.
Otherwise, a merchant token is required.

Endpoint: POST /oauth2/token
Version: V2 Beta
Security: Bearer

## Description:

  - `Obtaining API Tokens` ()
    There are two ways to get a valid API token: Obtaining a new token or Refreshing an existing token. The endpoint for obtaining a new API token or to refresh an existing one is the same.Only the request body fields are different.Selecting the appropriate option displays the relevant fields and information. Obtaining a new tokenA new token must be obtained because: No token exists.This may be from the user just logging in or the previous API token expired.The stored refresh_token expired, has been revoked, or gets rejected by the server (such as a refresh attempt failed).A different API key is being used. To obtain a new API token, see the call below, selecting Obtain a new token.This displays the fields and details needed to make the call. Refreshing an existing tokenAn existing API token may be refreshed to create a new, valid API token.That existing API token may be currently valid or has expired recently.The goal is to provide continuous operation.This allows users to remain authenticated without repeating full credential authentication on every renewal. An API token may be refreshed because: The current access_token is about to or has already expired.A valid refresh_token is currently available and valid from the most recent API token. To refresh an API token, see the call below, selecting Refresh an existing token.This displays the fields and details needed to make the call.

  - `API Token Types` ()
    API token types depend on the type of API keys used to create them.The resulting API token type will be one of following: Merchant token if it is created from a merchant API key.Partner token if it is created from a partner API key. The two API keys types are not interchangeable.Most Flute endpoints require a merchant token.The endpoint description specifies the required API key type.Endpoints requiring a partner token will be explicitly marked.Otherwise, a merchant token is required.

## Security:

  - `Bearer` (unknown)
    http bearer JWT

## Request fields (application/x-www-form-urlencoded):

  - `client_id` (string, required)
    Specifies client ID from the API key for the account.

Example: 59483870959438697242c
    Example: 59483870959438697242c

  - `client_secret` (string, required)
    Specifies the client secret from the API key for the account.

Example: 9eb2c6859daa4d8ae5da02a9
    Example: 9eb2c6859daa4d8ae5da02a9

  - `grant_type` (string, required)
    Specifies the literal value `client_credentials`.
Example: client_credentials
    Enum: "client_credentials"

  - `scope` (string, required)
    Specifies the literal value `offline_access`.
Example: offline_access
    Enum: "offline_access"

  - `grant_type` (string, required)
    Specifies the literal value `refresh_token`.
Example: refresh_token
    Enum: "refresh_token"

  - `refresh_token` (string, required)
    Specifies the refresh token received from a prior token request.

Example: YhjQpM...EVkVuB
    Example: YhjQpM...EVkVuB

## Response 200:

  - `200` (unknown)
    OK. The API token was issued successfully.

## Response 200 fields (application/json):

  - `access_token` (string, required)
    Indicates the API token.

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

  - `token_type` (string, required)
    Indicates the token type.

Example: Bearer
    Example: Bearer

  - `expires_in` (integer)
    Indicates the expiration period (in seconds) of the API token.

Example: 900
    Example: 900

  - `refresh_token` (string)
    Indicates the refresh token (only for authorization_code grant).
Example: 324c08b9-0c1d-4e2f-3a4b-5c6d7e8f9a25
    Example: 324c08b9-0c1d-4e2f-3a4b-5c6d7e8f9a25

  - `scope` (string)
    Indicates the granted scopes, space-delimited.

Example: null
    Example: null

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `details` (string)
    Indicates details about the error.

Example: Unauthorized
    Example: Unauthorized

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Response | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)
    Indicates the source of the error.
Example: <Service>
    Example: <Service>

  - `exceptionType` (string)
    Indicates the error's exception type.

Example: FluentValidation.ValidationException
    Example: FluentValidation.ValidationException

  - `correlationId` (string)
    Indicates the correlation identifier.

This is a unique identifier, a trace identifier, Flute attaches to a request/response pair so a single transaction can be traced end-to-end across systems and logs. 

Its intent is to support troubleshooting.
We recommend including this value when contacting support.

Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
    Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef

  - `entityId` (string)
    Indicates the entity identifier.
This is a field on Flute's standard error response object, alongside values such as `correlationId`, `errorCode`, or `statusCode`.
It's the identifier of the specific resource the failed request was about.
Error messages may specify "Entity with ID b31fbe9f-eebb-45ce-9cae-92265389f47f does not exist or has been deleted."
When a 404 (or similar entity-specific error, like a conflict) comes back,
check `entityId` to get the exact identifier of the record that couldn't be found or matched.
This is useful for confirming which resource reference was wrong, especially if the request touched multiple identifiers at once.
Example: null

  - `errorCode` (string)
    Indicates the error code.
Example:
null

  - `title` (string)
    Indicates a short, human-readable summary of the error category.

Example: Resource not found
    Example: Resource not found

  - `cause` (string)
    Indicates the reason the error occurred.

Example: The requested resource does not exist or has been deleted.
    Example: The requested resource does not exist or has been deleted.

  - `resolution` (string)
    Indicates the recommended action for resolving the error.

Example: Verify the resource ID is correct or retrieve a list of available resources.
    Example: Verify the resource ID is correct or retrieve a list of available resources.

  - `documentationUrl` (string)
    https://developer.flute.com/

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 401 fields (application/json):

  - `details` (string)
    Indicates details about the error.

Example: Unauthorized
    Example: Unauthorized

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Response | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)
    Indicates the source of the error.
Example: <Service>
    Example: <Service>

  - `exceptionType` (string)
    Indicates the error's exception type.

Example: FluentValidation.ValidationException
    Example: FluentValidation.ValidationException

  - `correlationId` (string)
    Indicates the correlation identifier.

This is a unique identifier, a trace identifier, Flute attaches to a request/response pair so a single transaction can be traced end-to-end across systems and logs. 

Its intent is to support troubleshooting.
We recommend including this value when contacting support.

Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
    Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef

  - `entityId` (string)
    Indicates the entity identifier.
This is a field on Flute's standard error response object, alongside values such as `correlationId`, `errorCode`, or `statusCode`.
It's the identifier of the specific resource the failed request was about.
Error messages may specify "Entity with ID b31fbe9f-eebb-45ce-9cae-92265389f47f does not exist or has been deleted."
When a 404 (or similar entity-specific error, like a conflict) comes back,
check `entityId` to get the exact identifier of the record that couldn't be found or matched.
This is useful for confirming which resource reference was wrong, especially if the request touched multiple identifiers at once.
Example: null

  - `errorCode` (string)
    Indicates the error code.
Example:
null

  - `title` (string)
    Indicates a short, human-readable summary of the error category.

Example: Resource not found
    Example: Resource not found

  - `cause` (string)
    Indicates the reason the error occurred.

Example: The requested resource does not exist or has been deleted.
    Example: The requested resource does not exist or has been deleted.

  - `resolution` (string)
    Indicates the recommended action for resolving the error.

Example: Verify the resource ID is correct or retrieve a list of available resources.
    Example: Verify the resource ID is correct or retrieve a list of available resources.

  - `documentationUrl` (string)
    https://developer.flute.com/

## Response 500:

  - `500` (unknown)
    Internal Server Error

## Response 500 fields (application/json):

  - `details` (string)
    Indicates details about the error.

Example: Unauthorized
    Example: Unauthorized

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Response | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)
    Indicates the source of the error.
Example: <Service>
    Example: <Service>

  - `exceptionType` (string)
    Indicates the error's exception type.

Example: FluentValidation.ValidationException
    Example: FluentValidation.ValidationException

  - `correlationId` (string)
    Indicates the correlation identifier.

This is a unique identifier, a trace identifier, Flute attaches to a request/response pair so a single transaction can be traced end-to-end across systems and logs. 

Its intent is to support troubleshooting.
We recommend including this value when contacting support.

Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
    Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef

  - `entityId` (string)
    Indicates the entity identifier.
This is a field on Flute's standard error response object, alongside values such as `correlationId`, `errorCode`, or `statusCode`.
It's the identifier of the specific resource the failed request was about.
Error messages may specify "Entity with ID b31fbe9f-eebb-45ce-9cae-92265389f47f does not exist or has been deleted."
When a 404 (or similar entity-specific error, like a conflict) comes back,
check `entityId` to get the exact identifier of the record that couldn't be found or matched.
This is useful for confirming which resource reference was wrong, especially if the request touched multiple identifiers at once.
Example: null

  - `errorCode` (string)
    Indicates the error code.
Example:
null

  - `title` (string)
    Indicates a short, human-readable summary of the error category.

Example: Resource not found
    Example: Resource not found

  - `cause` (string)
    Indicates the reason the error occurred.

Example: The requested resource does not exist or has been deleted.
    Example: The requested resource does not exist or has been deleted.

  - `resolution` (string)
    Indicates the recommended action for resolving the error.

Example: Verify the resource ID is correct or retrieve a list of available resources.
    Example: Verify the resource ID is correct or retrieve a list of available resources.

  - `documentationUrl` (string)
    https://developer.flute.com/