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

# Authenticate

> Exchange your clientId and clientSecret for a short-lived access token

Before making any other Runtime API call, your visual must exchange its credentials for a Bearer token.

## Endpoint

```
POST /api/v1/runtime/clients/token
```

No `Authorization` header required for this call.

## Request body

```json theme={null}
{
  "clientId": "rc_xxxxxxxxxxxxxxxx",
  "clientSecret": "cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

| Field          | Type   | Required | Description                                                    |
| -------------- | ------ | -------- | -------------------------------------------------------------- |
| `clientId`     | string | ✓        | The Client ID from your Runtime Client credentials             |
| `clientSecret` | string | ✓        | The Client Secret (shown once at creation — store it securely) |

## Response

```json theme={null}
{
  "accessToken": "eyJhbGci...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}
```

| Field         | Description                                             |
| ------------- | ------------------------------------------------------- |
| `accessToken` | Bearer token to use in all subsequent Runtime API calls |
| `tokenType`   | Always `"Bearer"`                                       |
| `expiresIn`   | Token lifetime in seconds (typically 3600 = 1 hour)     |

## Using the token

Pass the `accessToken` as the `Authorization` header on all subsequent calls:

```
Authorization: Bearer eyJhbGci...
```

## Error responses

| Status | Code                     | Meaning                                            |
| ------ | ------------------------ | -------------------------------------------------- |
| `400`  | `INVALID_REQUEST`        | Missing or blank `clientId` or `clientSecret`      |
| `401`  | `INVALID_RUNTIME_CLIENT` | Credentials not found, revoked, or secret mismatch |

## When to call it

Call `authenticate` once at the start of each show — on `Event BeginPlay` or when the operator clicks a "Start Show" button in your visual. The token lasts 1 hour, which covers a typical live event. If your show runs longer, re-authenticate before the token expires.

```
Event BeginPlay
    ↓
HTTP POST /runtime/clients/token  { clientId, clientSecret }
    ↓
Store accessToken in a variable
    ↓
POST /runtime/events/start  (next step)
```