API tokens API

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

This page as Markdown

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 for what each role allows, and Create and manage 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. 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.

bash

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

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

{
  "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.

bash

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

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

{
  "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 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, with the full value in token.

bash

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"
  }'

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

{
  "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, with the value masked.

bash

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" }'

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

{
  "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 -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/apiTokens/tkn_2rT5yU7iO9pA1sD3fG6hJ8kL4zX \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"

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

{
  "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.

API tokens: Do the same in the app, and choose the right role.
MCP tokens API: Tokens for AI assistants that use the MCP server.

API tokens API

The API token object #

List API tokens #

Path parameters #

Response #

Get API token #

Path parameters #

Response #

Create API token #

Path parameters #

Body parameters #

Response #

Update API token #

Path parameters #

Body parameters #

Response #

Delete API token #

Path parameters #

Response #

Errors #

Related #

The API token object

List API tokens

Path parameters

Response

Get API token

Path parameters

Response

Create API token

Path parameters

Body parameters

Response

Update API token

Path parameters

Body parameters

Response

Delete API token

Path parameters

Response

Errors

Related