## Список порталов

`GET /v1/portals`

Возвращает порталы, в которых состоит владелец менеджмент-ключа, и его роль на каждом портале.

## Примеры

Запрос принимает только менеджмент-ключ — см. [Ограничения](/docs/management-keys#ограничения).

### curl — менеджмент-ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/portals" \
  -H "X-Api-Key: YOUR_MANAGEMENT_KEY"
```

### JavaScript — менеджмент-ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/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('Порталов с ролью администратора:', adminPortals.length)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив порталов |
| `data[].id` | string | Идентификатор портала. Его принимает параметр `portalId` эндпоинтов [`GET /v1/keys`](/docs/management-keys/list) и [`POST /v1/keys`](/docs/management-keys/create) |
| `data[].name` | string | Название портала |
| `data[].domain` | string | Домен портала |
| `data[].role` | string | Роль владельца на портале: `ADMIN` или `MEMBER` |

## Пример ответа

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

## Пример ответа при ошибке

401 — запрос отправлен ключом портала:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 403 | `MANAGEMENT_SCOPE_REQUIRED` | У менеджмент-ключа нет скоупа `vibe:mgmt:portals` |
| 401 | `WRONG_KEY_TYPE` | Запрос отправлен ключом портала — личным `vibe_api_` или ключом авторизации `vibe_app_`. Эндпоинт принимает только менеджмент-ключ |
| 401 | `KEY_INACTIVE` | Менеджмент-ключ отозван или заблокирован |
| 401 | `KEY_EXPIRED` | Срок действия менеджмент-ключа закончился |
| 401 | `INVALID_API_KEY` | Ключ с переданным значением не найден |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |

Отказы `OWNER_DELETED`, `OWNER_BLOCKED` и `ACCOUNT_PENDING_ERASURE` зависят от аккаунта владельца ключа — см. [Состояние аккаунта владельца](/docs/management-keys#состояние-аккаунта-владельца).

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Портал в списке не гарантирует доступа к его ключам.** В ответ попадают и порталы, где участие владельца неактивно. [`GET /v1/keys`](/docs/management-keys/list) с таким `portalId` отвечает `403 PORTAL_ACCESS_BLOCKED`.

**Порядок не задан, пагинации нет.** Ответ содержит все порталы владельца, порядок элементов от вызова к вызову не гарантирован.

## Смотрите также

- [Список API-ключей портала](/docs/management-keys/list)
- [Создать API-ключ](/docs/management-keys/create)
- [Менеджмент-ключи](/docs/management-keys)