## 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](/docs/management-keys#limitations).

### curl — management key

```bash
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 |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of Bitrix24 accounts |
| `data[].id` | string | Bitrix24 account ID. Accepted by the `portalId` parameter of [`GET /v1/keys`](/docs/management-keys/list) and [`POST /v1/keys`](/docs/management-keys/create) |
| `data[].name` | string | Bitrix24 account name |
| `data[].domain` | string | Bitrix24 account domain |
| `data[].role` | string | The 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 |
|------|-----|----------|
| 403 | `MANAGEMENT_SCOPE_REQUIRED` | The management key lacks the `vibe:mgmt:portals` 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).

For the full list of common API errors, see [Errors](/docs/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`](/docs/management-keys/list) 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

- [List Bitrix24 account API keys](/docs/management-keys/list)
- [Create an API key](/docs/management-keys/create)
- [Management keys](/docs/management-keys)