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

# Authentication

> Generate and use access tokens.

Key2Arena uses OAuth 2.0 Client Credentials for server-to-server authentication.

Each API client receives a unique **Client ID** and **Client Secret**.

> [!NOTE]
>
> Access tokens are valid for 1 hour. Request a new token when the current one expires.

## Generate an access token

Send a request to:

```http theme={null}
POST https://api.key2arena.com/v1/oauth/token
```

Use `application/x-www-form-urlencoded` and provide your credentials, requested scopes, and the `client_credentials` grant type.

```bash theme={null}
curl --request POST \
  --url https://api.key2arena.com/v1/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'scope=products:read orders:read orders:create balance:read'
```

## Token response

A successful request returns an access token:

```json theme={null}
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "YOUR_ACCESS_TOKEN"
}
```

Access tokens are valid for **1 hour**.

When a token expires, request a new one using the same Client ID and Client Secret.

## Use the access token

Include the token in the `Authorization` header of every authenticated request:

```http theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Example:

```bash theme={null}
curl --request GET \
  --url https://api.key2arena.com/v1/products \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

## Scopes

Scopes control which endpoints an access token can access.

| Scope | Access |
| - | - |
| `products:read` | Read products, pricing, and availability |
| `orders:read` | Read orders and delivered content |
| `orders:create` | Create new orders |
| `balance:read` | Read the available balance |

Request only the scopes enabled for your API client.

For example, a token used only to browse the catalog can request:

```text theme={null}
products:read
```

A full ordering integration can request:

```text theme={null}
products:read orders:read orders:create balance:read
```

## Authentication errors

Requests without a valid access token return:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Authentication credentials are missing, invalid, or expired.",
    "request_id": "req_..."
  }
}
```

If the token is valid but does not include the required scope:

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "The access token does not have permission to perform this action.",
    "required_scopes": [
      "orders:create"
    ],
    "request_id": "req_..."
  }
}
```

> [!NOTE]
>
> Each API client is linked to a Key2Arena customer account. Products, pricing, balance, and orders are automatically resolved for that customer.


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