## Получить API-ключ

`GET /v1/keys/:id`

Возвращает запись одного API-ключа владельца менеджмент-ключа по её идентификатору, без значения ключа.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `id` (path) | string | да | Идентификатор записи ключа. Список: [`GET /v1/keys`](/docs/management-keys/list) |

## Примеры

Запрос принимает только менеджмент-ключ — см. [Ограничения](/docs/management-keys#ограничения).

### curl — менеджмент-ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/keys/6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc" \
  -H "X-Api-Key: YOUR_MANAGEMENT_KEY"
```

### JavaScript — менеджмент-ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/keys/6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc', {
  headers: {
    'X-Api-Key': 'YOUR_MANAGEMENT_KEY',
  },
})

const { success, data } = await res.json()
console.log('Ключ:', data.name, '—', data.status)
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data.id` | string | Идентификатор записи ключа |
| `data.name` | string | Название ключа, заданное при создании |
| `data.prefix` | string | Первые символы значения ключа |
| `data.suffix` | string | Последние четыре символа значения ключа |
| `data.type` | string | Тип записи ключа, всегда `APP` |
| `data.userId` | string | Идентификатор владельца ключа |
| `data.portalId` | string | Идентификатор портала |
| `data.clientId` | string \| null | Идентификатор клиента OAuth, если он записан на ключе. Иначе `null` |
| `data.scopes` | array | [Скоупы](/docs/scopes) ключа |
| `data.ipWhitelist` | array | Разрешённые IP-адреса. Пустой массив — без ограничения |
| `data.expiresAt` | string \| null | Дата окончания срока действия (ISO 8601), `null` — бессрочный |
| `data.rateLimit` | number \| null | Индивидуальный лимит запросов к AI-эндпоинтам, `null` — общий лимит платформы |
| `data.status` | string | `ACTIVE`, `REVOKED`, `EXPIRED` или `BLOCKED` |
| `data.lastUsedAt` | string \| null | Дата последнего запроса этим ключом (ISO 8601) |
| `data.createdAt` | string | Дата создания (ISO 8601) |
| `data.updatedAt` | string | Дата последнего изменения (ISO 8601) |
| `data.accessMode` | string | `READWRITE` или `READONLY` |
| `data.totalDefault` | boolean \| null | Приходит ли `meta.total` в списках, запрошенных этим ключом. `null` — действует настройка платформы |
| `data.issuedVia` | string \| null | Канал, которым выписан вебхук ключа: `per-portal` и `cloud-shared` — модуль-коннектор на портале, `dev_key` — ключ разработчика владельца, `legacy` — регистрация через Битрикс24 Network, `none` — вебхук не заводился, у ключа только права `vibe:*`. `null`, если канал не записан |
| `data.b24Ready` | boolean \| null | Есть ли у ключа рабочие учётные данные для запросов к Битрикс24. `null` у ключа авторизации приложения и у ключа только со скоупами `vibe:*` |

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

```json
{
  "success": true,
  "data": {
    "id": "6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc",
    "name": "Интеграция с CRM",
    "prefix": "vibe_api_XXXXXXXXX",
    "suffix": "XXXX",
    "type": "APP",
    "userId": "fafa9780-eed7-4d29-b040-2448d924f452",
    "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
    "clientId": null,
    "scopes": ["crm", "task", "im", "vibe:ai", "vibe:search", "vibe:storage"],
    "ipWhitelist": [],
    "expiresAt": null,
    "rateLimit": null,
    "status": "ACTIVE",
    "lastUsedAt": "2026-10-23T10:01:53.371Z",
    "createdAt": "2026-10-14T07:07:00.732Z",
    "updatedAt": "2026-10-23T10:01:53.371Z",
    "accessMode": "READWRITE",
    "totalDefault": null,
    "issuedVia": "cloud-shared",
    "b24Ready": true
  }
}
```

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

404 — ключ не найден:

```json
{
  "success": false,
  "error": {
    "code": "KEY_NOT_FOUND",
    "message": "API key not found"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 404 | `KEY_NOT_FOUND` | Ключа с таким `id` нет, он принадлежит другому пользователю или это менеджмент-ключ |
| 403 | `MANAGEMENT_SCOPE_REQUIRED` | У менеджмент-ключа нет скоупа `vibe:mgmt:keys` |
| 401 | `WRONG_KEY_TYPE` | Запрос отправлен ключом портала — личным `vibe_api_` или ключом авторизации `vibe_app_`. Эндпоинт принимает только менеджмент-ключ |
| 401 | `KEY_INACTIVE` | Менеджмент-ключ отозван или заблокирован |
| 401 | `KEY_EXPIRED` | Срок действия менеджмент-ключа закончился |
| 401 | `INVALID_API_KEY` | Ключ с переданным значением не найден |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |

Отказы `OWNER_DELETED`, `OWNER_BLOCKED` и `ACCOUNT_PENDING_ERASURE` зависят от аккаунта владельца ключа — см. [Состояние аккаунта владельца](/docs/management-keys#состояние-аккаунта-владельца).

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

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

**Проверяется владение, а не членство в портале.** Запись своего ключа читается, даже когда доступ владельца к порталу ключа отключён и [`GET /v1/keys`](/docs/management-keys/list) с этим `portalId` отвечает `403 PORTAL_ACCESS_BLOCKED`.

**Неактивный ключ читается так же, как активный.** Запись отозванного, истёкшего или заблокированного ключа возвращается с текущим значением `status`.

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

- [Список API-ключей портала](/docs/management-keys/list)
- [Изменить API-ключ](/docs/management-keys/update)
- [Удалить API-ключ](/docs/management-keys/delete)
- [Перевыпустить API-ключ](/docs/management-keys/rotate)
- [Менеджмент-ключи](/docs/management-keys)