# Authentication

Obtain an OAuth 2.0 access token and authenticate Axiym API requests.

Product: Account API
Guides follow API reference 0.3.0 and event reference 0.2.0.
Canonical page: https://docs.axiym.io/account-api/integration-guide/fundamentals/authentication

The Axiym API platform uses OAuth 2.0 client credentials. Exchange your partner
credentials for a short-lived access token, then send it on protected requests.

The token authorizes the scopes and resources configured for your
integration. Each endpoint documents its required scope and resource path.

## Request an access token

`POST /oauth/token` uses `application/x-www-form-urlencoded`. Do not send an
`Authorization` header on this request.

```sh
curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/oauth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=$AXIYM_CLIENT_ID" \
  --data-urlencode "client_secret=$AXIYM_CLIENT_SECRET" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=$AXIYM_SCOPE"
```

| Parameter       | Value                                                                      |
| --------------- | -------------------------------------------------------------------------- |
| `client_id`     | OAuth client identifier issued by Axiym.                                   |
| `client_secret` | OAuth client secret issued by Axiym.                                       |
| `grant_type`    | `client_credentials`.                                                      |
| `scope`         | Space-delimited scopes required by the API and issued to your integration. |

```json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "<requested_scope>",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni..."
}
```

## Authenticate API requests

Send the access token in the `Authorization` header of every protected API
request:

```http
Authorization: Bearer <access_token>
```

Store `client_secret` server-side in an environment-specific secret store.
Sandbox and production credentials are separate.

Track `expires_in` and obtain a new token before the current token expires. If
a token is missing, expired, or invalid, request a new token and retry the
original request once.