# Obtains or refreshes an API token

<a id="get-oauth-token"></a>
<span class="api-endpoint">POST {{<a href="#baseOAuthURL">baseOAuthURL</a>}}/oauth2/token</span>
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**<br>
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**<br>
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

## 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 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 expiry, or lifetime, (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 fields (application/json):

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

Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error
    Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error

  - `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 Status | 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.

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

  - `entityId` (string)
    Indicates the entity identifier.
Example:
null

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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

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

## Response 401 fields (application/json):

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

Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error
    Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error

  - `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 Status | 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.

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

  - `entityId` (string)
    Indicates the entity identifier.
Example:
null

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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

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

## Response 500 fields (application/json):

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

Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error
    Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error

  - `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 Status | 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.

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

  - `entityId` (string)
    Indicates the entity identifier.
Example:
null

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

  - `title` (string)

  - `cause` (string)

  - `resolution` (string)

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