## List server tokens

`GET /v1/infra/servers/:id/access-tokens`

Returns the server's tokens filtered by status. By default, only active tokens are returned.

## Parameters

| Parameter | In | Type | Required | Description |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | yes | BLACKHOLE server ID. List: [`GET /v1/infra/servers`](/docs/infra/servers/list) |
| `status` | query | string | no | Filter: `active` (default) \| `expired` \| `revoked` \| `all`. A value outside this set is not rejected — the query then behaves as if `all` were passed |

## Examples

### curl — personal key

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-tokens?status=active"
```

### curl — OAuth application

```bash
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-tokens?status=active"
```

### JavaScript — personal key

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access-tokens?status=active`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const result = await res.json()
if (!res.ok || result.success !== true) {
  throw new Error(result.error?.code ?? `HTTP_${res.status}`)
}
const { data } = result
console.log(`Active tokens: ${data.tokens.length} / ${data.limits.activeCountMax}`)
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access-tokens?status=active`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const result = await res.json()
if (!res.ok || result.success !== true) {
  throw new Error(result.error?.code ?? `HTTP_${res.status}`)
}
const { data } = result
console.log(`Active tokens: ${data.tokens.length} / ${data.limits.activeCountMax}`)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data.tokens` | array | Array of tokens |
| `data.tokens[].id` | string | Token ID |
| `data.tokens[].mode` | string | `"api-bearer"` or `"share-url"` |
| `data.tokens[].createdVia` | string | Where the token was minted from: `PLATFORM` — via the API or the Vibecode interface, `BITRIX24_PORTAL` — from the Bitrix24 side when an application link is published |
| `data.tokens[].name` | string \| null | Token label |
| `data.tokens[].identityBound` | boolean | For `api-bearer` always `true`; for `share-url` — whether login via Bitrix24 is required |
| `data.tokens[].shortcode` | string \| null | Link code for `share-url`; `null` for `api-bearer` |
| `data.tokens[].expiresAt` | string (ISO 8601) | Expiration timestamp |
| `data.tokens[].revokedAt` | string (ISO 8601) \| null | Revocation timestamp; `null` if not revoked |
| `data.tokens[].createdAt` | string (ISO 8601) | Mint timestamp |
| `data.tokens[].lastUsedAt` | string (ISO 8601) \| null | Last use timestamp |
| `data.tokens[].sessionCount` | number | Number of sessions created through this token |
| `data.tokens[].createdBy.id` | string | ID of the user who minted the token |
| `data.tokens[].createdBy.name` | string | User name |
| `data.tokens[].createdBy.email` | string | User email |
| `data.limits.activeCount` | number | Current number of the server's active tokens |
| `data.limits.activeCountMax` | number | Active token limit per server (100) |
| `data.limits.mintRateLimitPerHour` | number | Hourly mint limit per API key (50) |
| `data.limits.mintsLastHour` | number | Number of tokens minted in the last hour for this API key |

## Response example

```json
{
  "success": true,
  "data": {
    "tokens": [
      {
        "id": "9f1c4b7e-3d52-4a18-9c0e-7b2a1f6d84c3",
        "mode": "api-bearer",
        "createdVia": "PLATFORM",
        "name": "ci-smoke",
        "identityBound": true,
        "shortcode": null,
        "expiresAt": "2026-05-18T10:50:00.000Z",
        "revokedAt": null,
        "createdAt": "2026-05-18T10:40:00.000Z",
        "lastUsedAt": "2026-05-18T10:41:30.000Z",
        "sessionCount": 1,
        "createdBy": { "id": "c4e8b1a7-6f30-4d92-8a15-3b7e0c2d94f6", "name": "John Brown", "email": "john@example.bitrix24.com" }
      },
      {
        "id": "2a7d5e61-84bc-4f39-b0d7-5e6c9a3f1b28",
        "mode": "share-url",
        "createdVia": "BITRIX24_PORTAL",
        "name": "preview",
        "identityBound": false,
        "shortcode": "R8k3Zm2P",
        "expiresAt": "2026-06-17T08:44:00.000Z",
        "revokedAt": null,
        "createdAt": "2026-05-18T08:44:00.000Z",
        "lastUsedAt": null,
        "sessionCount": 0,
        "createdBy": { "id": "c4e8b1a7-6f30-4d92-8a15-3b7e0c2d94f6", "name": "John Brown", "email": "john@example.bitrix24.com" }
      }
    ],
    "limits": {
      "activeCount": 2,
      "activeCountMax": 100,
      "mintRateLimitPerHour": 50,
      "mintsLastHour": 1
    }
  }
}
```

## Error response example

404 — server not found:

```json
{
  "success": false,
  "error": {
    "code": "SERVER_NOT_FOUND",
    "message": "Server not found"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | No API key was supplied through `X-Api-Key` or a supported `Authorization: Bearer` scheme |
| 401 | `INVALID_API_KEY` | The authentication key is not recognized |
| 401 | `KEY_INACTIVE` | The requesting API key is no longer active |
| 401 | `KEY_EXPIRED` | The requesting API key has expired; this is distinct from resource URL expiry |
| 401 | `NO_PORTAL` | A non-management key has no portal binding |
| 401 | `COWORK_CHAT_KEY_INACTIVE` | The parent device key behind a Cowork chat key is no longer usable |
| 401 | `WRONG_AUTH_SCHEME` | An OAuth application key was sent as a Bearer session: put the key in `X-Api-Key` and the session in `Authorization: Bearer` |
| 401 | `INVALID_SESSION` | The supplied OAuth session is invalid or expired |
| 401 | `TOKEN_EXPIRED` | The OAuth user token expired and its refresh failed; re-authorization is required |
| 401 | `TOKEN_INVALID` | When the partner AI plane is enabled, its supplied token is unknown or expired |
| 401 | `KEY_REVOKED` | The partner credential behind the AI plane token is revoked |
| 402 | `ACCOUNT_FROZEN` | The key owner’s account is frozen. With wallet-debt scoping disabled, the shared API-key guard refuses this call before its handler. Follow error.topupUrl to resolve the balance; this status alone does not authorize repeating a prior write. |
| 403 | `TOKEN_OWNER_MISMATCH` | The server belongs to a different API key. Being on the server's development team does not grant access to this operation — it requires the managing key regardless of your role. |
| 403 | `PORTAL_COLLABORATOR_KEY_OUT_OF_SCOPE` | This operation is outside the development-team key route list. Use the key that manages the server |
| 403 | `EXTERNAL_COLLABORATOR_KEY_OUT_OF_SCOPE` | This operation is outside the external-collaborator key route list. Use the key that manages the server |
| 403 | `IP_NOT_ALLOWED` | The caller IP is outside the key allowlist. |
| 403 | `OWNER_BLOCKED` | The key owner is blocked. |
| 403 | `OWNER_DELETED` | The key owner was deleted. |
| 403 | `PORTAL_SUSPENDED` | The bound portal is suspended. |
| 403 | `PORTAL_DELETED` | The bound portal was deleted. |
| 403 | `PORTAL_BLOCKED` | The bound portal is blocked. |
| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | The management key lacks the portal binding or entity authority required by this call. |
| 403 | `AGENT_MAINTENANCE_KEY_OUT_OF_SCOPE` | The maintenance key route list does not include this operation. |
| 403 | `APP_API_KEY_OUT_OF_SCOPE` | The application key route list does not include this operation. |
| 403 | `WAITLIST_PENDING` | The key owner has not been activated. |
| 403 | `SESSION_APP_MISMATCH` | The OAuth session belongs to another application. |
| 403 | `PLANE_FORBIDDEN` | The partner key does not allow this AI plane. |
| 403 | `SYSTEM_FORBIDDEN` | The partner key does not allow this AI system. |
| 403 | `SCOPE_FORBIDDEN` | The partner AI plane forbids this route. |
| 403 | `CONNECT_COMPANY_DERIVED_TOKEN_FORBIDDEN` | A company connection key cannot manage derived tokens. |
| 404 | `SERVER_NOT_FOUND` | Server not found or deleted |
| 404 | `NOT_FOUND` | The server's portal has been deactivated |
| 429 | `QUOTA_EXCEEDED` | API billing is enabled with a nonzero overage price: the daily free quota is exhausted and the PREPAY balance is not positive. Top up the balance. `error.quota` and `error.used` report counts; `X-RateLimit-Quota`, `X-RateLimit-Used` and `X-RateLimit-Remaining` report the quota, usage and zero remainder. This refusal does not promise `Retry-After` or `X-RateLimit-Scope` |
| 429 | `CALLER_RATE_LIMITED` | The shared key or user request limit. Wait for the number of seconds specified in `Retry-After`; `X-RateLimit-Scope` identifies the refusing layer |
| 503 | `FEATURE_DISABLED` | The access-tokens section is disabled on the platform. The pre-call signal and the fallback are described in [Availability](/docs/infra/access-tokens#availability) |
| 503 | `ACCOUNT_PENDING_ERASURE` | The key owner is pending erasure or being erased. Header `Retry-After: 3600`. |
| 503 | `SERVICE_DISABLED` | The partner AI plane or its quota-readiness service is disabled. No `Retry-After` is promised for this refusal. |
| 503 | `user_self_deletion_pending` | The API key owner scheduled self-deletion. The token plugin refuses the call before its handler. Header `Retry-After: 604800`. |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **The `token` field (JWT) is not included in the list.** The JWT is returned only in the response to [minting](./create.md) or [refreshing](./refresh.md) a token.
- **`status=all` returns expired and revoked tokens.** A token's status is derived from the `revokedAt` (not `null` → revoked) and `expiresAt` (earlier than the current time → expired) fields.
- **The list is capped at 500 tokens.** The `status` filter narrows the selection to the desired category.

## See also

- [Mint a token](./create.md)
- [Revoke a token](./delete.md)
- [Access tokens](/docs/infra/access-tokens)