# API tokens API

> List, create, rename, change the role of and delete the API tokens that scripts, integrations and SDKs use to call ApiTraffic.

Source: https://www.apitraffic.io/docs/api-reference/api-tokens

API tokens are the credentials your SDKs, scripts and integrations send in the `Authorization` header. Each token belongs to one environment and has a role (`administrator`, `user` or `ingest`) that decides what it may do. See [API token roles](https://www.apitraffic.io/docs/api-reference/introduction#api-token-roles) for what each role allows, and [Create and manage API tokens](https://www.apitraffic.io/docs/account/api-tokens) for doing this in the app.

**Permissions:** any member can list and read tokens. Creating, changing and deleting a token needs an owner or admin session, or an `administrator` API token.

> **Note:** The token value is returned once, in the response to [Create API token](#create-api-token). Every other response shows a hint such as `tok_Xr8Kq*******O5kQw`, so store the value somewhere safe when you create it.

## The API token object

- **sid (string, required)**:
  The token's identifier (`tkn_…`). Use it in paths. It is not the credential.

- **accountSid (string, required)**:
  The account the token belongs to.

- **environmentSid (string | null, required)**:
  The environment the token was created for. An SDK that sends traffic with this token sends it to this environment.

- **name (string, required)**:
  The token's name.

- **role (string, required)**:
  `administrator`, `user` or `ingest`.

- **token (string | null)**:
  The credential (`tok_…`) in the create response; a masked hint everywhere else.

- **createdAt (string, required)**:
  When the token was created (ISO 8601).

- **updatedAt (string | null, required)**:
  When the token was last changed.

- **lastUsedAt (string | null)**:
  When the token was last used, to within about five minutes. `null` if never.

- **firstUsedAt (string | null)**:
  When the token first saw traffic. `null` if never, or not since this started being recorded.

## List API tokens

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/apiTokens`

Returns every API token in the account, across all environments, sorted by name. The token values are masked.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier (`acc_` followed by 27 letters and digits).

### Response

- **hasMore (boolean, required)**:
  Always `false`: every token is returned in one response.

- **records (object[], required)**:
  The tokens, as [API token objects](#the-api-token-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/apiTokens \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/apiTokens`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { records } = await response.json();
const unused = records.filter((token) => token.lastUsedAt === null);
```

```json 200
{
  "hasMore": false,
  "records": [
    {
      "sid": "tkn_2kF9wQ4mX7pL1vB8nR3tZ6cH5yJ",
      "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
      "environmentSid": "prd7k2",
      "name": "Acme Store API (production SDK)",
      "role": "ingest",
      "token": "tok_Xr8Kq*******O5kQw",
      "createdAt": "2026-03-02T15:40:00.000Z",
      "updatedAt": "2026-03-02T15:40:00.000Z",
      "lastUsedAt": "2026-10-19T14:05:00.000Z",
      "firstUsedAt": "2026-03-02T15:52:13.000Z"
    },
    {
      "sid": "tkn_2rT5yU7iO9pA1sD3fG6hJ8kL4zX",
      "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
      "environmentSid": "prd7k2",
      "name": "Deploy pipeline",
      "role": "user",
      "token": "tok_Pq3Wn*******e7Yt2",
      "createdAt": "2026-04-11T09:12:30.000Z",
      "updatedAt": "2026-04-11T09:12:30.000Z",
      "lastUsedAt": "2026-10-19T09:00:41.000Z",
      "firstUsedAt": "2026-04-11T09:30:02.000Z"
    }
  ]
}
```

## Get API token

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/apiTokens/{apiTokenSid}`

Returns one API token. The token value is masked.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **apiTokenSid (path, string, required)**:
  The token's identifier (`tkn_…`).

### Response

An [API token object](#the-api-token-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/apiTokens/tkn_2kF9wQ4mX7pL1vB8nR3tZ6cH5yJ \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const apiTokenSid = 'tkn_2kF9wQ4mX7pL1vB8nR3tZ6cH5yJ';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/apiTokens/${apiTokenSid}`,
  { headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` } },
);
const token = await response.json();
```

```json 200
{
  "sid": "tkn_2kF9wQ4mX7pL1vB8nR3tZ6cH5yJ",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "environmentSid": "prd7k2",
  "name": "Acme Store API (production SDK)",
  "role": "ingest",
  "token": "tok_Xr8Kq*******O5kQw",
  "createdAt": "2026-03-02T15:40:00.000Z",
  "updatedAt": "2026-03-02T15:40:00.000Z",
  "lastUsedAt": "2026-10-19T14:05:00.000Z",
  "firstUsedAt": "2026-03-02T15:52:13.000Z"
}
```

## Create API token

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/apiTokens`

Creates a token for one environment. The response is the only time the full token value is returned.

**Permissions:** owner or admin, or an `administrator` API token. **Limit:** the number of API tokens an account can hold depends on its plan; past it, the API answers `409` with code `2213`.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

### Body parameters

- **name (body, string, required)**:
  A name that says where the token is used, for example `Deploy pipeline`.

- **role (body, string, required)**:
  `administrator`, `user` or `ingest`. Use `ingest` for a token an SDK uses to send traffic: it can fetch the SDK's settings, and nothing else. Use `administrator` for a token your server mints [embed tokens](https://www.apitraffic.io/docs/integrations/embed) with; no other role can. An administrator token can read the account's captured traffic through the embeds it mints, so revoke it at once if it leaks.

- **environmentSid (body, string, required)**:
  The environment the token belongs to (6 letters and digits). Traffic an SDK sends with this token is recorded in this environment.

### Response

An [API token object](#the-api-token-object), with the full value in `token`.

```bash cURL
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/apiTokens \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy pipeline",
    "role": "user",
    "environmentSid": "prd7k2"
  }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/apiTokens`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Deploy pipeline', role: 'user', environmentSid: 'prd7k2' }),
});
const created = await response.json();
// Store created.token now: it is never returned again.
```

```json 200
{
  "sid": "tkn_2rT5yU7iO9pA1sD3fG6hJ8kL4zX",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "environmentSid": "prd7k2",
  "name": "Deploy pipeline",
  "role": "user",
  "token": "tok_Pq3WnL8vK2xR5tB9mZ1cH4yF7jD0sA6gE3uQ8ie7Yt2",
  "createdAt": "2026-10-19T14:10:00.000Z",
  "updatedAt": "2026-10-19T14:10:00.000Z",
  "lastUsedAt": null,
  "firstUsedAt": null
}
```

## Update API token

`PUT https://api.apitraffic.io/v1/accounts/{accountSid}/apiTokens/{apiTokenSid}`

Renames a token or changes its role. A role change takes effect on the token's next request. The token value and environment do not change; to move a token to another environment, create a new one.

**Permissions:** owner or admin, or an `administrator` API token.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **apiTokenSid (path, string, required)**:
  The token's identifier (`tkn_…`).

### Body parameters

Send both fields, even if only one changes.

- **name (body, string, required)**:
  The token's name.

- **role (body, string, required)**:
  `administrator`, `user` or `ingest`.

### Response

The updated [API token object](#the-api-token-object), with the value masked.

```bash cURL
curl -X PUT https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/apiTokens/tkn_2rT5yU7iO9pA1sD3fG6hJ8kL4zX \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Deploy pipeline (read only)", "role": "user" }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const apiTokenSid = 'tkn_2rT5yU7iO9pA1sD3fG6hJ8kL4zX';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/apiTokens/${apiTokenSid}`,
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'Deploy pipeline (read only)', role: 'user' }),
  },
);
const updated = await response.json();
```

```json 200
{
  "sid": "tkn_2rT5yU7iO9pA1sD3fG6hJ8kL4zX",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "environmentSid": "prd7k2",
  "name": "Deploy pipeline (read only)",
  "role": "user",
  "token": "tok_Pq3Wn*******e7Yt2",
  "createdAt": "2026-10-19T14:10:00.000Z",
  "updatedAt": "2026-10-19T14:12:00.000Z",
  "lastUsedAt": null,
  "firstUsedAt": null
}
```

## Delete API token

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/apiTokens/{apiTokenSid}`

Deletes a token. It stops working immediately, on every server. This cannot be undone.

> **Warning:** If an SDK uses the token, that application stops sending traffic and stops receiving configuration. Create the replacement and deploy it first, then delete the old token.

**Permissions:** owner or admin, or an `administrator` API token.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **apiTokenSid (path, string, required)**:
  The token's identifier (`tkn_…`).

### Response

- **sid (string, required)**:
  The deleted token's identifier.

- **deleted (boolean, required)**:
  `true`.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/apiTokens/tkn_2rT5yU7iO9pA1sD3fG6hJ8kL4zX \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const apiTokenSid = 'tkn_2rT5yU7iO9pA1sD3fG6hJ8kL4zX';
await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/apiTokens/${apiTokenSid}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
```

```json 200
{
  "sid": "tkn_2rT5yU7iO9pA1sD3fG6hJ8kL4zX",
  "deleted": true
}
```

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| `400` | `1000` | A field is missing or invalid, for example a `role` other than the three allowed. |
| `403` | `2010` | Creating, changing or deleting a token without owner, admin or `administrator` access. |
| `404` | `4000` | No token with that `apiTokenSid` in this account. |
| `409` | `2213` | The plan's API token limit is reached. Delete an unused token, or upgrade. |
| `503` | `2108` | The change could not be applied on every server right now. Nothing was changed; retry. |

## Related

- [API tokens](https://www.apitraffic.io/docs/account/api-tokens):
    Do the same in the app, and choose the right role.

- [MCP tokens API](https://www.apitraffic.io/docs/api-reference/mcp-tokens):
    Tokens for AI assistants that use the MCP server.