For AI agents: markdown of this page — /docs-content-en/management-keys/list.md documentation index — /llms.txt

List Bitrix24 account API keys

GET /v1/keys

Returns the management key owner's API keys on the specified Bitrix24 account: personal keys and application authorization keys.

Parameters

Parameter Type Required Description
ParameterportalId (query) Typestring Requiredyes DescriptionBitrix24 account ID. List: GET /v1/portals. The management key owner must be a member of this account

No pagination: the response contains all of the owner's keys on the account, newest first.

Examples

The request accepts only a management key — see Limitations.

curl — management key

Terminal 
curl "https://vibecode.bitrix24.com/v1/keys?portalId=0d9f7744-f853-47c7-b06e-6f61f9dd1b7f" \
  -H "X-Api-Key: YOUR_MANAGEMENT_KEY"

JavaScript — management key

javascript 
const portalId = '0d9f7744-f853-47c7-b06e-6f61f9dd1b7f'

const res = await fetch(`https://vibecode.bitrix24.com/v1/keys?portalId=${portalId}`, {
  headers: {
    'X-Api-Key': 'YOUR_MANAGEMENT_KEY',
  },
})

const { success, data } = await res.json()
const activeKeys = data.filter((key) => key.status === 'ACTIVE')
console.log('Active keys:', activeKeys.length)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of keys
Fielddata[].id Typestring DescriptionKey record ID. Accepted by GET /v1/keys/:id and by endpoints that take a key as a resource — for example, targetApiKeyId in bot ownership transfer
Fielddata[].name Typestring DescriptionKey name set at creation
Fielddata[].prefix Typestring DescriptionFirst characters of the key value
Fielddata[].suffix Typestring DescriptionLast four characters of the key value
Fielddata[].type Typestring DescriptionKey record type, always APP
Fielddata[].userId Typestring DescriptionKey owner ID
Fielddata[].portalId Typestring DescriptionBitrix24 account ID
Fielddata[].clientId Typestring | null DescriptionOAuth client ID, if recorded on the key. Otherwise null
Fielddata[].scopes Typearray DescriptionKey scopes
Fielddata[].ipWhitelist Typearray DescriptionAllowed IP addresses. An empty array means no restriction
Fielddata[].expiresAt Typestring | null DescriptionExpiration date (ISO 8601), null — no expiration
Fielddata[].rateLimit Typenumber | null DescriptionIndividual request limit for AI endpoints, null — the platform-wide limit
Fielddata[].status Typestring DescriptionACTIVE, REVOKED, EXPIRED or BLOCKED
Fielddata[].lastUsedAt Typestring | null DescriptionDate of the last request made with this key (ISO 8601)
Fielddata[].createdAt Typestring DescriptionCreation date (ISO 8601)
Fielddata[].updatedAt Typestring DescriptionDate of the last update (ISO 8601)
Fielddata[].accessMode Typestring DescriptionREADWRITE or READONLY
Fielddata[].totalDefault Typeboolean | null DescriptionWhether meta.total is returned in lists requested with this key. null — the platform setting applies
Fielddata[].issuedVia Typestring | null DescriptionChannel 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
Fielddata[].b24Ready Typeboolean | null DescriptionWhether 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
    },
    {
      "id": "ef0b2172-aa01-445c-815c-f8ce82559d5e",
      "name": "Application authorization key",
      "prefix": "vibe_app_XXXXXXXXX",
      "suffix": "XXXX",
      "type": "APP",
      "userId": "fafa9780-eed7-4d29-b040-2448d924f452",
      "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
      "clientId": null,
      "scopes": ["crm", "vibe:infra", "vibe:ai", "vibe:search", "vibe:storage"],
      "ipWhitelist": [],
      "expiresAt": null,
      "rateLimit": null,
      "status": "REVOKED",
      "lastUsedAt": null,
      "createdAt": "2026-08-27T06:36:58.910Z",
      "updatedAt": "2026-08-27T06:37:01.459Z",
      "accessMode": "READWRITE",
      "totalDefault": null,
      "issuedVia": null,
      "b24Ready": null
    }
  ]
}

Error response example

400 — portalId was not sent:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PORTAL_ID",
    "message": "Query parameter portalId is required"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PORTAL_ID DescriptionThe portalId parameter was not sent
HTTP403 CodeNOT_PORTAL_MEMBER DescriptionThe management key owner is not a member of the Bitrix24 portal with the given portalId
HTTP403 CodePORTAL_ACCESS_BLOCKED DescriptionThe owner's access to the Bitrix24 portal is disabled: their membership is inactive or denied by the portal's access policy
HTTP403 CodeMANAGEMENT_SCOPE_REQUIRED DescriptionThe management key lacks the vibe:mgmt:keys scope
HTTP401 CodeWRONG_KEY_TYPE DescriptionThe 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
HTTP401 CodeKEY_INACTIVE DescriptionThe management key has been revoked or blocked
HTTP401 CodeKEY_EXPIRED DescriptionThe management key has expired
HTTP401 CodeINVALID_API_KEY DescriptionNo key with the given value was found
HTTP401 CodeMISSING_API_KEY DescriptionThe 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.

The full list of common API errors — Errors.

Known specifics

Inactive keys in the list. The response includes revoked, expired and blocked keys. Working keys are the elements with status: "ACTIVE".

The key value is not returned. The prefix and suffix fields do not authorize requests: they help you recognize your key in the list. The key value arrives once — in the response to creation or rotation.

See also