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

# API Tokens

> Manage API tokens for programmatic access to your ApiTraffic account

## List API Tokens

<api-endpoint method="GET" url="https://api.apitraffic.io/v1/accounts/{accountSid}/apiTokens" />

Retrieve all API tokens associated with an account.

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier (format: `acc_` followed by 27 alphanumeric characters)
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Response

<ResponseField name="hasMore" type="boolean">
  Indicates if there are more records to paginate through
</ResponseField>

<ResponseField name="records" type="array">
  <Expandable title="API Token Objects">
    <ResponseField name="sid" type="string">
      Unique API token identifier
    </ResponseField>

    <ResponseField name="accountSid" type="string">
      Account identifier this token belongs to
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the API token
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of the token's purpose
    </ResponseField>

    <ResponseField name="scopes" type="array">
      Array of permission scopes granted to this token
    </ResponseField>

    <ResponseField name="lastUsedAt" type="string">
      ISO 8601 timestamp of last token usage (nullable)
    </ResponseField>

    <ResponseField name="expiresAt" type="string">
      ISO 8601 timestamp when token expires (nullable for no expiration)
    </ResponseField>

    <ResponseField name="isActive" type="boolean">
      Whether this token is currently active
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of token creation
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens" \
    -H "Authorization: Bearer your-jwt-token"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens', {
    headers: {
      'Authorization': 'Bearer your-jwt-token'
    }
  });

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens',
      headers={'Authorization': 'Bearer your-jwt-token'}
  )

  tokens = response.json()
  print(tokens)
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "hasMore": false,
    "records": [
      {
        "sid": "tok_abc123def456ghi789jkl012",
        "accountSid": "acc_abc123def456ghi789jkl012",
        "name": "Production API Token",
        "description": "Token for production monitoring integration",
        "scopes": ["buckets:read", "requests:read", "metrics:read"],
        "lastUsedAt": "2023-12-01T14:30:00.000Z",
        "expiresAt": "2024-12-01T00:00:00.000Z",
        "isActive": true,
        "createdAt": "2023-12-01T10:30:00.000Z"
      },
      {
        "sid": "tok_xyz789uvw012rst345abc",
        "accountSid": "acc_abc123def456ghi789jkl012",
        "name": "CI/CD Token",
        "description": "Token for automated testing and deployment",
        "scopes": ["buckets:read", "buckets:write"],
        "lastUsedAt": null,
        "expiresAt": null,
        "isActive": true,
        "createdAt": "2023-11-15T09:15:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Get API Token

<api-endpoint method="GET" url="https://api.apitraffic.io/v1/accounts/{accountSid}/apiTokens/{apiTokenSid}" />

Retrieve details of a specific API token.

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

<ParamField path="apiTokenSid" type="string" required>
  API token identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Response

Returns a single API token object with the same structure as described in the List API Tokens response.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens/tok_abc123def456ghi789jkl012" \
    -H "Authorization: Bearer your-jwt-token"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens/tok_abc123def456ghi789jkl012', {
    headers: {
      'Authorization': 'Bearer your-jwt-token'
    }
  });

  const token = await response.json();
  console.log(token);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "tok_abc123def456ghi789jkl012",
    "accountSid": "acc_abc123def456ghi789jkl012",
    "name": "Production API Token",
    "description": "Token for production monitoring integration",
    "scopes": ["buckets:read", "requests:read", "metrics:read"],
    "lastUsedAt": "2023-12-01T14:30:00.000Z",
    "expiresAt": "2024-12-01T00:00:00.000Z",
    "isActive": true,
    "createdAt": "2023-12-01T10:30:00.000Z"
  }
  ```
</ResponseExample>

***

## Create API Token

<api-endpoint method="POST" url="https://api.apitraffic.io/v1/accounts/{accountSid}/apiTokens" />

Create a new API token for programmatic access.

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  Name of the API token
</ParamField>

<ParamField body="description" type="string">
  Description of the token's purpose
</ParamField>

<ParamField body="scopes" type="array" required>
  Array of permission scopes to grant to this token
</ParamField>

<ParamField body="expiresAt" type="string">
  ISO 8601 timestamp when token should expire (optional, null for no expiration)
</ParamField>

### Response

<ResponseField name="sid" type="string">
  Unique API token identifier
</ResponseField>

<ResponseField name="token" type="string">
  The actual API token value (only returned on creation)
</ResponseField>

<ResponseField name="accountSid" type="string">
  Account identifier
</ResponseField>

<ResponseField name="name" type="string">
  Name of the API token
</ResponseField>

<ResponseField name="description" type="string">
  Description of the token
</ResponseField>

<ResponseField name="scopes" type="array">
  Array of granted permission scopes
</ResponseField>

<ResponseField name="expiresAt" type="string">
  Expiration timestamp (nullable)
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Whether the token is active
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of creation
</ResponseField>

<Warning>
  The token value is only returned once during creation. Store it securely as it cannot be retrieved again.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens" \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Analytics Token",
      "description": "Token for analytics dashboard integration",
      "scopes": ["metrics:read", "buckets:read"],
      "expiresAt": "2024-12-31T23:59:59.000Z"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Analytics Token',
      description: 'Token for analytics dashboard integration',
      scopes: ['metrics:read', 'buckets:read'],
      expiresAt: '2024-12-31T23:59:59.000Z'
    })
  });

  const token = await response.json();
  console.log(token);
  // Store token.token securely!
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens',
      headers={
          'Authorization': 'Bearer your-jwt-token',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Analytics Token',
          'description': 'Token for analytics dashboard integration',
          'scopes': ['metrics:read', 'buckets:read'],
          'expiresAt': '2024-12-31T23:59:59.000Z'
      }
  )

  token = response.json()
  print(token)
  # Store token['token'] securely!
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "tok_new789uvw012rst345def",
    "token": "at_live_1234567890abcdef...",
    "accountSid": "acc_abc123def456ghi789jkl012",
    "name": "Analytics Token",
    "description": "Token for analytics dashboard integration",
    "scopes": ["metrics:read", "buckets:read"],
    "expiresAt": "2024-12-31T23:59:59.000Z",
    "isActive": true,
    "createdAt": "2023-12-01T15:45:00.000Z"
  }
  ```
</ResponseExample>

***

## Update API Token

<api-endpoint method="PUT" url="https://api.apitraffic.io/v1/accounts/{accountSid}/apiTokens/{apiTokenSid}" />

Update an existing API token's metadata.

<Info>
  You cannot update the token value itself or its scopes. To change scopes, create a new token and delete the old one.
</Info>

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

<ParamField path="apiTokenSid" type="string" required>
  API token identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Request Body

<ParamField body="name" type="string" required>
  Name of the API token
</ParamField>

<ParamField body="description" type="string">
  Description of the token's purpose
</ParamField>

<ParamField body="isActive" type="boolean" required>
  Whether this token should be active
</ParamField>

### Response

Returns the updated API token object (without the token value).

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens/tok_abc123def456ghi789jkl012" \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Production Token",
      "description": "Updated description for production monitoring",
      "isActive": false
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens/tok_abc123def456ghi789jkl012', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Updated Production Token',
      description: 'Updated description for production monitoring',
      isActive: false
    })
  });

  const token = await response.json();
  console.log(token);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "tok_abc123def456ghi789jkl012",
    "accountSid": "acc_abc123def456ghi789jkl012",
    "name": "Updated Production Token",
    "description": "Updated description for production monitoring",
    "scopes": ["buckets:read", "requests:read", "metrics:read"],
    "lastUsedAt": "2023-12-01T14:30:00.000Z",
    "expiresAt": "2024-12-01T00:00:00.000Z",
    "isActive": false,
    "createdAt": "2023-12-01T10:30:00.000Z"
  }
  ```
</ResponseExample>

***

## Delete API Token

<api-endpoint method="DELETE" url="https://api.apitraffic.io/v1/accounts/{accountSid}/apiTokens/{apiTokenSid}" />

Delete an API token, immediately revoking access.

<Warning>
  This action is irreversible. Any applications using this token will immediately lose access.
</Warning>

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

<ParamField path="apiTokenSid" type="string" required>
  API token identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Response

<ResponseField name="sid" type="string">
  ID of the deleted API token
</ResponseField>

<ResponseField name="deleted" type="boolean">
  Flag indicating the token was successfully deleted
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens/tok_abc123def456ghi789jkl012" \
    -H "Authorization: Bearer your-jwt-token"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/apiTokens/tok_abc123def456ghi789jkl012', {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer your-jwt-token'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "tok_abc123def456ghi789jkl012",
    "deleted": true
  }
  ```
</ResponseExample>

***

## Available Scopes

API tokens can be granted specific scopes to limit their access:

### Bucket Scopes

* `buckets:read` - View bucket information
* `buckets:write` - Create and modify buckets
* `buckets:delete` - Delete buckets

### Request Scopes

* `requests:read` - View request data
* `requests:write` - Modify request metadata (notes, etc.)
* `requests:delete` - Delete individual requests

### Metrics Scopes

* `metrics:read` - Access analytics and metrics data

### Redaction Scopes

* `redactions:read` - View redaction rules
* `redactions:write` - Create and modify redaction rules
* `redactions:delete` - Delete redaction rules

### Exclusion Scopes

* `exclusions:read` - View exclusion rules
* `exclusions:write` - Create and modify exclusion rules
* `exclusions:delete` - Delete exclusion rules

### Workflow Scopes

* `workflows:read` - View workflow configurations
* `workflows:write` - Create and modify workflows
* `workflows:delete` - Delete workflows

### Token Management Scopes

* `tokens:read` - View API token information
* `tokens:write` - Create and modify API tokens
* `tokens:delete` - Delete API tokens

***

## Using API Tokens

Once created, use your API token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer at_live_1234567890abcdef..." \
  https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/buckets
```

### Token Format

* **Live tokens**: `at_live_` followed by random characters
* **Test tokens**: `at_test_` followed by random characters

### Best Practices

1. **Principle of Least Privilege**: Only grant the minimum scopes required
2. **Regular Rotation**: Rotate tokens periodically for security
3. **Secure Storage**: Store tokens securely, never in plain text
4. **Monitor Usage**: Check `lastUsedAt` to identify unused tokens
5. **Set Expiration**: Use expiration dates for temporary access
6. **Environment Separation**: Use different tokens for different environments