Create an API key

POST /v1/keys

Creates a personal API key on the specified Bitrix24 account on behalf of the management key owner. Fields are passed flat at the root of the JSON body.

Request fields (body)

Four platform scopes are added to the requested ones: vibe:infra, vibe:ai, vibe:search, vibe:storage. The key from the examples below gets crm, task and these four.

On a Bitrix24 account where the administrator has turned server management off, vibe:infra is dropped from this set without an error — the key is issued with the other three. The 403 INFRA_DISABLED_FOR_PORTAL refusal arrives only for a scope explicitly listed in scopes.

To get a key with exactly the listed scopes, pass exactScopes: true. The body {"portalId": "…", "name": "Storage only", "scopes": ["crm", "vibe:storage"], "exactScopes": true} issues a key with only crm and vibe:storage, and it answers POST /v1/infra/servers and AI calls with 403. The scopes of such a key are final: the platform does not widen them at request time, so GET /v1/me returns exactly what was stored at issue time.

The placement, entity and userfieldtype scopes are unavailable to a personal key and are not stored: the scopes of the created key in the response do not contain them, even when they were in the request alongside data scopes. The userfieldconfig scope is stored.

Examples

This endpoint accepts only a management key — see Limitations.

curl — management key

curl -X POST "https://vibecode.bitrix24.com/v1/keys" \
  -H "X-Api-Key: YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
    "name": "Deal export",
    "scopes": ["crm", "task"]
  }'

JavaScript — management key

const res = await fetch('https://vibecode.bitrix24.com/v1/keys', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_MANAGEMENT_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    portalId: '0d9f7744-f853-47c7-b06e-6f61f9dd1b7f',
    name: 'Deal export',
    scopes: ['crm', 'task'],
  }),
})

const { success, data } = await res.json()
// The key value arrives only once — save it to a secrets store
const apiKey = data.rawKey
console.log('Key created:', data.id, data.scopes)

Response fields

Response example

{
  "success": true,
  "data": {
    "id": "3c1f6a52-8e4b-4d07-9a1e-5b2d7f0c6e91",
    "name": "Deal export",
    "type": "APP",
    "userId": "fafa9780-eed7-4d29-b040-2448d924f452",
    "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
    "clientId": null,
    "scopes": ["crm", "task", "vibe:infra", "vibe:ai", "vibe:search", "vibe:storage"],
    "ipWhitelist": [],
    "expiresAt": null,
    "rateLimit": null,
    "status": "ACTIVE",
    "lastUsedAt": null,
    "createdAt": "2026-10-29T12:23:14.701Z",
    "updatedAt": "2026-10-29T12:23:14.701Z",
    "accessMode": "READWRITE",
    "totalDefault": null,
    "issuedVia": "cloud-shared",
    "rawKey": "vibe_api_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

Error response example

400 — portalId not provided:

{
  "success": false,
  "error": {
    "code": "MISSING_PORTAL_ID",
    "message": "Field portalId is required"
  }
}

Errors

The OWNER_DELETED, OWNER_BLOCKED, ACCOUNT_PENDING_ERASURE and B24_USER_DELETED refusals depend on the key owner's account — see Owner account state.

Two platform access checks. The first is the Bitrix24 account access check. A commercial Bitrix24 plan grants full access, a demo plan grants a trial, and an account on a free plan gets 402 INT_TARIFF_REQUIRED. A self-hosted Bitrix24 account where self-hosted Bitrix24 is not yet served gets 402 SELFHOSTED_NOT_AVAILABLE. One more outcome of the same check comes with status 403 and means the platform has nothing to name: PORTAL_TARIFF_UNREADABLE. This check applies only to issuing a new key: rotation, automatic key recovery and ownership handover are not subject to it, and already issued keys keep working.

The second check runs later, and its reach is wider: Bitrix24 itself refuses the issuance because the account plan does not include Vibecode. It fires on everything that issues a key — creation, rotation, automatic key recovery and ownership handover. Where access can be purchased, the response is 402 INT_VIBE_PLUS_REQUIRED. Where there is nothing to offer — 502 CONNECTOR_PLAN_REQUIRED. Retrying a request with either code will not help until the Bitrix24 plan changes.

Refusals shared with rotation. The issuance refusals themselves also arrive on rotation — which ones exactly is listed in Rotate an API key. The body of an issuance refusal may carry an error.reason field with the exact cause in the platform's internal classification, while error.code stays the same. Branch on error.code, not on the message text.

Full list of common API errors — Errors.

See also

• List Bitrix24 account API keys
• Get an API key
• Update an API key
• Delete an API key
• Rotate an API key
• List Bitrix24 accounts
• Scopes
• Management keys