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

# Create a one-time token

> Mints a single-use, short-lived bearer token from the API key that authenticates this request. The token authenticates exactly one HTTP request or WebSocket connection to the APIs its parent key can reach, then expires. Authenticate with the API key itself — bearer callers are refused. See the [one-time tokens guide](https://docs.inworld.ai/portal/ephemeral-tokens.md) for semantics and client patterns.


## API reference

**Endpoint:** `POST https://api.inworld.ai/auth/v1/tokens`

### Authorization

- `Authorization` (string; required) — Your [authentication](https://docs.inworld.ai/portal/authentication.md) credentials. Populate `Basic $INWORLD_API_KEY` — one-time tokens are minted with the parent API key itself, never with a bearer token.

### Request body

Content type: `application/json`

- `single_use` (boolean; required) — Must be `true`. Only single-use tokens are supported; the token is consumed by its first successful authentication.
- `ttl` (string) — How long the token stays valid, as a duration in seconds (e.g. `"300s"`). Minimum 1 second, maximum 1 hour; defaults to 15 minutes. Mutually exclusive with `expire_time`.
- `expire_time` (string) — Absolute expiry timestamp, as an alternative to `ttl`. Capped at 1 hour from now. Mutually exclusive with `ttl`.
- `client_reference_id` (string) — Optional correlation ID of your own (for example a user or session ID). Printable ASCII, at most 256 characters. Echoed in the response and attached to the token for usage attribution.

#### Request example

```json
{
  "single_use": true,
  "ttl": "300s",
  "expire_time": "string",
  "client_reference_id": "string"
}
```

### Response

Status: `200`. Content type: `application/json`.

- `name` (string) — The token's resource name, `tokens/{token}`. This is the token's stable ID — safe to log and correlate on.
- `accessToken` (string) — The bearer credential. Returned only in this response and never stored — send it as `Authorization: Bearer <accessToken>`, or as `Sec-WebSocket-Protocol: bearer_<accessToken>` on browser WebSocket connections.
- `expireTime` (string) — When the token expires.
- `singleUse` (boolean) — Always `true`. The token is consumed by its first successful authentication.
- `clientReferenceId` (string) — The correlation ID from the request, if one was given.
- `createTime` (string) — When the token was minted.
- `apiKey` (string) — Resource name of the parent API key, `workspaces/{workspace}/apikeys/{key}`. Deleting that key immediately invalidates this token.

### Response examples

#### 200: minted

```json
{
  "name": "tokens/1f0d8e9a-1d2b-4c3d-8e9f-0a1b2c3d4e5f",
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "expireTime": "2026-09-01T12:05:00Z",
  "singleUse": true,
  "clientReferenceId": "user-4711-session-42",
  "createTime": "2026-09-01T12:00:00Z",
  "apiKey": "workspaces/my-workspace/apikeys/4aa6d7e9-3a62-4e19-a031-9558852115f2"
}
```

### Code examples

#### cURL

```bash
curl https://api.inworld.ai/auth/v1/tokens \
  --request POST \
  --header "Authorization: Basic $INWORLD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "single_use": true,
    "ttl": "300s",
    "client_reference_id": "user-4711-session-42"
  }'
```

#### Python

```python
import requests

url = "https://api.inworld.ai/auth/v1/tokens"
headers = {
    "Authorization": "Basic <api-key>",
    "Content-Type": "application/json",
}
payload = {
    "single_use": True,
    "ttl": "300s",
    "client_reference_id": "user-4711-session-42",
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()["accessToken"])
```

#### JavaScript

```javascript
const response = await fetch('https://api.inworld.ai/auth/v1/tokens', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic <api-key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    single_use: true,
    ttl: '300s',
    client_reference_id: 'user-4711-session-42',
  }),
});

const token = await response.json();
console.log(token.accessToken);
```