Update an API key

PATCH /v1/keys/:id

Changes the settings of an API key owned by the management key owner. The body is flat, without a fields wrapper: pass only the fields that change.

Parameters

Request fields (body)

Examples

The request accepts only a management key — see Limitations.

curl — management key

curl -X PATCH "https://vibecode.bitrix24.com/v1/keys/6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc" \
  -H "X-Api-Key: YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM and tasks integration"
  }'

JavaScript — management key

const res = await fetch('https://vibecode.bitrix24.com/v1/keys/6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_MANAGEMENT_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'CRM and tasks integration',
  }),
})

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

Response fields

The response has no b24Ready field. To get it, call GET /v1/keys/:id.

Response example

{
  "success": true,
  "data": {
    "id": "6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc",
    "name": "CRM and tasks 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", "tasks", "im"],
    "ipWhitelist": [],
    "expiresAt": null,
    "rateLimit": null,
    "status": "ACTIVE",
    "lastUsedAt": "2026-10-28T13:11:06.013Z",
    "createdAt": "2026-05-18T10:22:10.950Z",
    "updatedAt": "2026-10-29T12:16:49.962Z",
    "accessMode": "READWRITE",
    "totalDefault": null,
    "issuedVia": null
  }
}

Error response example

403 — a Bitrix24 scope is being added to an application authorization key:

{
  "success": false,
  "error": {
    "code": "OAUTH_SCOPE_CHANGE_REQUIRES_REISSUE",
    "message": "An OAuth app's permissions can't be changed on an existing key — they're fixed when the key is issued. Create a new authorization key with the scopes you need."
  }
}

Errors

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

Full list of common API errors — Errors.

Known specifics

The access mode is changed with the mode field. The accessMode field from the response is not accepted in the request body: a request with it returns 200, and the key mode does not change.

A value equal to the current one is not a change. A client may send the whole key record to rename it: the same mode, the same rateLimit and the same scopes set go through without the checks that run when these fields change.

Scopes and status change in Bitrix24 as well. If the key's scopes are checked on the Bitrix24 side, the new set is first passed to the key's webhook and only then stored in Vibecode. If the Bitrix24 account refuses, the key keeps its previous scopes. On revocation the platform deletes the key's webhook in Bitrix24 or disables its credentials.

Revocation cancels the access tokens issued by the key. Together with the switch to REVOKED, the server access tokens issued by this key are revoked.

Platform-issued keys are checked only when returned to service or extended. Shortening the expiry, revoking and editing other fields of such keys work without the issuance checks. Ordinary dashboard keys are not affected by these checks.

The mode of Cowork/Code keys lives on the seat. A seat is a pair of an employee and a Bitrix24 account, shared by all of the employee's devices. So the mode of a desktop app key cannot be changed here, and on a third-party agent key billed to the subscription it is capped by the seat mode.

See also

• List Bitrix24 account API keys
• Create an API key
• Get an API key
• Delete an API key
• Rotate an API key
• Access mode
• Scopes
• Management keys