> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fexco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.0 authentication

> Authenticate with the Boarding API using the OAuth 2.0 client credentials flow.

The Boarding API uses the [OAuth 2.0 client credentials flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) to authenticate requests. You exchange your client
credentials for a short-lived access token, then include that token
in the `Authorization` header of every API call.

## Before you start

You need a `client_id` and `client_secret` issued by Fexco. Contact your
Fexco account manager or email
[merchantsupport@fexco.com](mailto:merchantsupport@fexco.com) to request
credentials.

## Request an access token

Send a `POST` request to `/oauth/accesstoken` on the Boarding API
base URL for your environment. See [Environments and URLs](https://docs.fexco.com/dcc/api-reference/environments.md)
for instructions to obtain the base URL for your environment. The request body must use
`application/x-www-form-urlencoded` encoding.

> [tab] Request
>
> ```bash theme={null}
> curl -X POST https://{your-base-url}/oauth/accesstoken \
>   -H "Content-Type: application/x-www-form-urlencoded" \
>   -d "grant_type=client_credentials" \
>   --data-urlencode "client_id=YOUR_CLIENT_ID" \
>   --data-urlencode "client_secret=YOUR_CLIENT_SECRET"
> ```

> [tab] Response
>
> Illustrative response only. Use the `expires_in` value returned by your token endpoint; the example does not establish the lifetime configured in your environment.
>
> ```json theme={null}
> {
>   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
>   "token_type": "Bearer",
>   "expires_in": 600
> }
> ```

The response contains the following fields:

| Field | Type | Description |
| :- | :- | :- |
| `access_token` | string | The bearer token to include in API requests. |
| `token_type` | string | Always `Bearer`. |
| `expires_in` | integer | Token lifetime in seconds. Use the value returned by the token endpoint; the response example shows `600` seconds. |

Once you have a token, pass it in the `Authorization: Bearer` header on
every Boarding API request. Every request also requires an
`X-Acquirer-ID` header, Fexco provides this value during onboarding.
See [Board merchants via the REST API](https://docs.fexco.com/dcc/guides/merchant-boarding/board-api.md).

## Token expiry

Access tokens expire. Use the `expires_in` value returned in the token
response to determine their lifetime in seconds.
Track the time you received the token and request a replacement before
it expires, allowing a safety margin. Use the token request above to
obtain a replacement. If a [`401 Unauthorized`](https://docs.fexco.com/dcc/api-reference/error-handling)
response occurs, request a new token and retry the call once.

## Token security

Apply the following practices when handling access tokens:

* All connections to the Boarding API must use [Transport Layer
  Security (TLS) 1.2 or higher](https://docs.fexco.com/dcc/guides/getting-started/security-setup.md#transport-encryption-tls). The API rejects plain HTTP connections.
* Never include access tokens in URLs, query strings, or application
  logs.
* Store your `client_id` and `client_secret` using your platform's
  secure secret storage, not in source code or configuration files.

## Next steps

* [Certificate and JWT authentication](https://docs.fexco.com/dcc/api-reference/authentication/jwt-pki.md):
  the authentication method used by the Rate Service Connect rate service.
* [Merchant boarding endpoints](https://docs.fexco.com/dcc/api-reference/endpoints/merchant-boarding):
  the Boarding API endpoints that use OAuth 2.0 authentication.
* [Error handling](https://docs.fexco.com/dcc/api-reference/error-handling.md): how the Boarding
  REST API reports authentication errors and other failures.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.