
## Список токенов сервера

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

Возвращает токены сервера с фильтрацией по статусу. По умолчанию — только активные.

## Параметры

| Параметр | В | Тип | Обяз. | Описание |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | да | ID BLACKHOLE-сервера. Список: [`GET /v1/infra/servers`](/docs/infra/servers/list) |
| `status` | query | string | нет | Фильтр: `active` (по умолч.) \| `expired` \| `revoked` \| `all`. Значение вне этого набора не отбрасывается — выборка ведёт себя как `all` |

## Примеры

### curl — личный ключ

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

### curl — OAuth-приложение

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

### JavaScript — личный ключ

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/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(`Активных токенов: ${data.tokens.length} / ${data.limits.activeCountMax}`)
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/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(`Активных токенов: ${data.tokens.length} / ${data.limits.activeCountMax}`)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.tokens` | array | Массив токенов |
| `data.tokens[].id` | string | ID токена |
| `data.tokens[].mode` | string | `"api-bearer"` или `"share-url"` |
| `data.tokens[].createdVia` | string | Откуда выпущен токен: `PLATFORM` — через API или интерфейс Вайбкод, `BITRIX24_PORTAL` — со стороны Битрикс24 при публикации ссылки на приложение |
| `data.tokens[].name` | string \| null | Метка токена |
| `data.tokens[].identityBound` | boolean | Для `api-bearer` всегда `true`, для `share-url` — требуется ли вход через Битрикс24 |
| `data.tokens[].shortcode` | string \| null | Код ссылки для `share-url`, `null` для `api-bearer` |
| `data.tokens[].expiresAt` | string (ISO 8601) | Момент истечения |
| `data.tokens[].revokedAt` | string (ISO 8601) \| null | Момент отзыва, `null` если не отозван |
| `data.tokens[].createdAt` | string (ISO 8601) | Момент выпуска |
| `data.tokens[].lastUsedAt` | string (ISO 8601) \| null | Последнее использование |
| `data.tokens[].sessionCount` | number | Число сессий, созданных через этот токен |
| `data.tokens[].createdBy.id` | string | ID пользователя, выпустившего токен |
| `data.tokens[].createdBy.name` | string | Имя пользователя |
| `data.tokens[].createdBy.email` | string | Электронная почта пользователя |
| `data.limits.activeCount` | number | Текущее число активных токенов сервера |
| `data.limits.activeCountMax` | number | Лимит активных токенов на сервер (100) |
| `data.limits.mintRateLimitPerHour` | number | Лимит выпусков в час на API-ключ (50) |
| `data.limits.mintsLastHour` | number | Количество выпущенных токенов за последний час по данному API-ключу |

## Пример ответа

```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": "Иван Петров", "email": "ivan@example.bitrix24.ru" }
      },
      {
        "id": "2a7d5e61-84bc-4f39-b0d7-5e6c9a3f1b28",
        "mode": "share-url",
        "createdVia": "BITRIX24_PORTAL",
        "name": "предпросмотр",
        "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": "Иван Петров", "email": "ivan@example.bitrix24.ru" }
      }
    ],
    "limits": {
      "activeCount": 2,
      "activeCountMax": 100,
      "mintRateLimitPerHour": 50,
      "mintsLastHour": 1
    }
  }
}
```

## Пример ответа при ошибке

404 — сервер не найден:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | Ключ не передан через `X-Api-Key` или поддерживаемую схему `Authorization: Bearer` |
| 401 | `INVALID_API_KEY` | Ключ авторизации не опознан |
| 401 | `KEY_INACTIVE` | Ключ, которым сделан запрос, больше не активен |
| 401 | `KEY_EXPIRED` | Истёк срок действия ключа API, которым сделан запрос; это не срок resource URL |
| 401 | `NO_PORTAL` | Ключ, не являющийся управляющим, не привязан к порталу |
| 401 | `COWORK_CHAT_KEY_INACTIVE` | Для ключа чата Коворк/Код родительский ключ устройства больше не пригоден |
| 401 | `WRONG_AUTH_SCHEME` | Ключ приложения OAuth передан как Bearer-сессия: передайте ключ в `X-Api-Key`, а сессию — в `Authorization: Bearer` |
| 401 | `INVALID_SESSION` | Переданная сессия OAuth недействительна или истекла |
| 401 | `TOKEN_EXPIRED` | Токен пользователя OAuth истёк, а его обновление не удалось; требуется повторная авторизация |
| 401 | `TOKEN_INVALID` | При включённом партнёрском контуре AI передан неизвестный или истёкший токен этого контура |
| 401 | `KEY_REVOKED` | Партнёрский ключ, связанный с токеном контура AI, отозван |
| 402 | `ACCOUNT_FROZEN` | Счёт владельца ключа заморожен. При выключенной развязке долга общий гард API-ключа отказывает до обработчика. Для восстановления баланса используйте error.topupUrl; сам статус не разрешает повтор предыдущей записи |
| 403 | `TOKEN_OWNER_MISMATCH` | Сервер принадлежит другому API-ключу. Членство в команде разработки сервера эту операцию не открывает — она требует управляющего ключа при любой роли. |
| 403 | `PORTAL_COLLABORATOR_KEY_OUT_OF_SCOPE` | Операция не входит в список доступных ключу команды разработки. Используйте ключ, управляющий сервером |
| 403 | `EXTERNAL_COLLABORATOR_KEY_OUT_OF_SCOPE` | Операция не входит в список доступных ключу внешнего участника. Используйте ключ, управляющий сервером |
| 403 | `IP_NOT_ALLOWED` | IP вызывающего не входит в разрешённый список ключа |
| 403 | `OWNER_BLOCKED` | Владелец ключа заблокирован |
| 403 | `OWNER_DELETED` | Владелец ключа удалён |
| 403 | `PORTAL_SUSPENDED` | Привязанный портал Битрикс24 приостановлен |
| 403 | `PORTAL_DELETED` | Привязанный портал Битрикс24 удалён |
| 403 | `PORTAL_BLOCKED` | Привязанный портал Битрикс24 заблокирован |
| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | У управляющего ключа нет необходимой привязки к порталу или прав доступа к его данным |
| 403 | `AGENT_MAINTENANCE_KEY_OUT_OF_SCOPE` | Вызов не входит в список маршрутов ключа обслуживания |
| 403 | `APP_API_KEY_OUT_OF_SCOPE` | Вызов не входит в список маршрутов ключа приложения |
| 403 | `WAITLIST_PENDING` | Владелец ключа ещё не активирован |
| 403 | `SESSION_APP_MISMATCH` | Сессия OAuth относится к другому приложению |
| 403 | `PLANE_FORBIDDEN` | Ключ партнёра не разрешает этот AI-контур |
| 403 | `SYSTEM_FORBIDDEN` | Ключ партнёра не разрешает эту AI-систему |
| 403 | `SCOPE_FORBIDDEN` | AI-контур партнёра запрещает этот маршрут |
| 403 | `CONNECT_COMPANY_DERIVED_TOKEN_FORBIDDEN` | Ключ подключения компании не может управлять производными токенами |
| 404 | `SERVER_NOT_FOUND` | Сервер не найден или удалён |
| 404 | `NOT_FOUND` | Портал сервера деактивирован |
| 429 | `QUOTA_EXCEEDED` | Включён платный учёт API с ненулевой ценой превышения квоты: суточная бесплатная квота исчерпана, баланс PREPAY неположительный. Пополните баланс. `error.quota` и `error.used` содержат счётчики; `X-RateLimit-Quota`, `X-RateLimit-Used` и `X-RateLimit-Remaining` — квоту, расход и нулевой остаток. Этот отказ не гарантирует `Retry-After` или `X-RateLimit-Scope` |
| 429 | `CALLER_RATE_LIMITED` | Общий лимит запросов ключа или пользователя. Подождите число секунд из `Retry-After`; `X-RateLimit-Scope` указывает отказавший уровень |
| 503 | `FEATURE_DISABLED` | Раздел токенов доступа выключен на платформе. Признак до вызова и запасной путь — [Доступность](/docs/infra/access-tokens#доступность) |
| 503 | `ACCOUNT_PENDING_ERASURE` | Владелец ключа ожидает удаления или уже удаляется. Заголовок `Retry-After: 3600` |
| 503 | `SERVICE_DISABLED` | AI-контур партнёра или сервис готовности его квоты выключен. Заголовок `Retry-After` для этого отказа не гарантирован |
| 503 | `user_self_deletion_pending` | Владелец API-ключа запланировал удаление. Проверка раздела токенов отказывает до обработчика. Заголовок `Retry-After: 604800` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- **Поле `token` (JWT) не включается в список.** JWT приходит только в ответе на [выпуск](./create.md) и на [обновление](./refresh.md) токена.
- **`status=all` возвращает истёкшие и отозванные токены.** Статус токена определяется по полям `revokedAt` (не `null` → отозван) и `expiresAt` (меньше текущего времени → истёк).
- **Список ограничен 500 токенами.** Фильтр `status` сужает выборку до нужной категории.

## Смотрите также

- [Выпустить токен](./create.md)
- [Отозвать токен](./delete.md)
- [Токены доступа](/docs/infra/access-tokens)
