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

List Bitrix24 accounts

GET /v1/portals

Returns the Bitrix24 accounts the management key owner belongs to, and the owner's role in each account.

Examples

The request accepts only a management key — see Limitations.

curl — management key

Terminal 
curl "https://vibecode.bitrix24.com/v1/portals" \
  -H "X-Api-Key: YOUR_MANAGEMENT_KEY"

JavaScript — management key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/portals', {
  headers: {
    'X-Api-Key': 'YOUR_MANAGEMENT_KEY',
  },
})

const { success, data } = await res.json()
const adminPortals = data.filter((portal) => portal.role === 'ADMIN')
console.log('Accounts with the administrator role:', adminPortals.length)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of Bitrix24 accounts
Fielddata[].id Typestring DescriptionBitrix24 account ID. Accepted by the portalId parameter of GET /v1/keys and POST /v1/keys
Fielddata[].name Typestring DescriptionBitrix24 account name
Fielddata[].domain Typestring DescriptionBitrix24 account domain
Fielddata[].role Typestring DescriptionThe owner's role in the account: ADMIN or MEMBER

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
      "name": "mycompany.bitrix24.com",
      "domain": "mycompany.bitrix24.com",
      "role": "ADMIN"
    },
    {
      "id": "5cd5138b-757a-4562-9646-6e2744deef27",
      "name": "sales-team.bitrix24.com",
      "domain": "sales-team.bitrix24.com",
      "role": "MEMBER"
    }
  ]
}

Error response example

401 — the request was sent with a Bitrix24 account key:

JSON 
{
  "success": false,
  "error": {
    "code": "WRONG_KEY_TYPE",
    "message": "This endpoint requires a MANAGEMENT key, not an APP key"
  }
}

Errors

HTTP Code Description
HTTP403 CodeMANAGEMENT_SCOPE_REQUIRED DescriptionThe management key lacks the vibe:mgmt:portals 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.

For the full list of common API errors, see Errors.

Known specifics

An account in the list does not guarantee access to its keys. The response also includes Bitrix24 accounts where the owner's membership is inactive. GET /v1/keys with such a portalId responds with 403 PORTAL_ACCESS_BLOCKED.

No defined order, no pagination. The response contains all of the owner's Bitrix24 accounts; the order of elements is not guaranteed between calls.

See also