## Get an API key

`GET /v1/keys/:id`

Returns a single API key record that belongs to the management key's owner, by record ID. The key value is not returned.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `id` (path) | string | yes | Key record ID. List: [`GET /v1/keys`](/docs/management-keys/list) |

## Examples

This endpoint accepts only a management key — see [Limitations](/docs/management-keys#limitations).

### curl — management key

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

### JavaScript — management key

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

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

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data.id` | string | Key record ID |
| `data.name` | string | Key name set at creation |
| `data.prefix` | string | First characters of the key value |
| `data.suffix` | string | Last four characters of the key value |
| `data.type` | string | Key record type, always `APP` |
| `data.userId` | string | Key owner ID |
| `data.portalId` | string | Bitrix24 account ID |
| `data.clientId` | string \| null | OAuth client ID, if recorded on the key. Otherwise `null` |
| `data.scopes` | array | Key [scopes](/docs/scopes) |
| `data.ipWhitelist` | array | Allowed IP addresses. An empty array means no restriction |
| `data.expiresAt` | string \| null | Expiration date (ISO 8601), `null` — no expiration |
| `data.rateLimit` | number \| null | Individual request limit for AI endpoints, `null` — the platform-wide limit |
| `data.status` | string | `ACTIVE`, `REVOKED`, `EXPIRED` or `BLOCKED` |
| `data.lastUsedAt` | string \| null | Date of the last request made with this key (ISO 8601) |
| `data.createdAt` | string | Creation date (ISO 8601) |
| `data.updatedAt` | string | Date of the last update (ISO 8601) |
| `data.accessMode` | string | `READWRITE` or `READONLY` |
| `data.totalDefault` | boolean \| null | Whether `meta.total` is returned in lists requested with this key. `null` — the platform setting applies |
| `data.issuedVia` | string \| null | Channel through which the key's webhook was issued: `per-portal` and `cloud-shared` — the connector module on the Bitrix24 account, `dev_key` — the owner's developer key, `legacy` — registration through Bitrix24 Network, `none` — no webhook was created, the key has only `vibe:*` permissions. `null` if the channel is not recorded |
| `data.b24Ready` | boolean \| null | Whether the key has working credentials for requests to Bitrix24. `null` for an application authorization key and for a key with only `vibe:*` scopes |

## Response example

```json
{
  "success": true,
  "data": {
    "id": "6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc",
    "name": "CRM integration",
    "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
  }
}
```

## Error response example

404 — the key was not found:

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

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 404 | `KEY_NOT_FOUND` | There is no key with this `id`, it belongs to another user, or it is a management key |
| 403 | `MANAGEMENT_SCOPE_REQUIRED` | The management key lacks the `vibe:mgmt:keys` scope |
| 401 | `WRONG_KEY_TYPE` | The request was sent with a Bitrix24 account key — a personal `vibe_api_` key or a `vibe_app_` authorization key. The endpoint accepts only a management key |
| 401 | `KEY_INACTIVE` | The management key has been revoked or blocked |
| 401 | `KEY_EXPIRED` | The management key has expired |
| 401 | `INVALID_API_KEY` | No key with the given value was found |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not sent |

The `OWNER_DELETED`, `OWNER_BLOCKED` and `ACCOUNT_PENDING_ERASURE` refusals depend on the key owner's account — see [Owner account state](/docs/management-keys#owner-account-state).

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

## Known specifics

**Ownership is checked, not membership in the Bitrix24 account.** A record of your own key is readable even when the owner's access to the key's account is disabled and [`GET /v1/keys`](/docs/management-keys/list) with this `portalId` responds with `403 PORTAL_ACCESS_BLOCKED`.

**An inactive key is read the same way as an active one.** The record of a revoked, expired or blocked key is returned with the current `status` value.

## See also

- [List Bitrix24 account API keys](/docs/management-keys/list)
- [Update an API key](/docs/management-keys/update)
- [Delete an API key](/docs/management-keys/delete)
- [Rotate an API key](/docs/management-keys/rotate)
- [Management keys](/docs/management-keys)