Для AI-агентов: markdown этой страницы — /docs-content/management-keys/portals.md индекс документации — /llms.txt

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

GET /v1/portals

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

Примеры

Запрос принимает только менеджмент-ключ — см. Ограничения.

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

Terminal 
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 и POST /v1/keys
Поле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 Код Описание
HTTP403 КодMANAGEMENT_SCOPE_REQUIRED ОписаниеУ менеджмент-ключа нет скоупа vibe:mgmt:portals
HTTP401 КодWRONG_KEY_TYPE ОписаниеЗапрос отправлен ключом портала — личным vibe_api_ или ключом авторизации vibe_app_. Эндпоинт принимает только менеджмент-ключ
HTTP401 КодKEY_INACTIVE ОписаниеМенеджмент-ключ отозван или заблокирован
HTTP401 КодKEY_EXPIRED ОписаниеСрок действия менеджмент-ключа закончился
HTTP401 КодINVALID_API_KEY ОписаниеКлюч с переданным значением не найден
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key

Отказы OWNER_DELETED, OWNER_BLOCKED и ACCOUNT_PENDING_ERASURE зависят от аккаунта владельца ключа — см. Состояние аккаунта владельца.

Полный список общих ошибок API — Ошибки.

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

Портал в списке не гарантирует доступа к его ключам. В ответ попадают и порталы, где участие владельца неактивно. GET /v1/keys с таким portalId отвечает 403 PORTAL_ACCESS_BLOCKED.

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

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