---
title: "Авторизация и правила API"
description: "Ключи, полномочия, ошибки, пагинация и идемпотентность."
group: "Техническая документация"
order: 20
---

## Адреса этого стенда

- Документация: https://context4.me/docs.md
- Индекс для агента: https://context4.me/docs/agent-index.json
- Консоль и подключения: https://console.context4.me/integrations
- MCP: https://context4.me/mcp
- HTTP API: https://context4.me/v1
- Composio base URL: https://context4.me/compat/context4/v1
- OpenAPI: https://context4.me/docs/openapi.json
- Каталог HTTP/MCP: https://context4.me/docs/api-index.json
- Маршруты Composio: https://context4.me/docs/compat-routes.json
- Коннекторы: https://context4.me/docs/connectors.json


# Авторизация и правила API

## Адрес и авторизация

Адрес API этого стенда: `https://context4.me/v1`. [Консоль и подключения](https://console.context4.me/integrations). Переменная `CONTEXT4_API_KEY` содержит ваш секретный ключ серверного окружения; документация его не подставляет.

```bash
curl "https://context4.me/v1/identity" \
  -H "Authorization: Bearer $CONTEXT4_API_KEY"
```

Ключ выпускается в консоли и показывается один раз. Его формат — `ctx4_<env>_<secret>`. Ключ ограничен областью организации и рабочего пространства и набором полномочий. Чужой tenant-ресурс возвращает `404 not_found`. Нужное полномочие каждого метода указано в [справочнике](https://context4.me/docs/api-reference.md).

| Полномочие | Назначение |
| --- | --- |
| `tools:read` | Инструменты и каталог HTTP-методов |
| `executions:read`, `executions:write` | Чтение и создание выполнений; proxy тоже требует write |
| `connections:read`, `connections:write` | Подключения, auth configs и источники |
| `connections:manage` | Дополнительное право управлять чужими подключениями внутри tenant; требует connections:write |
| `tool-sessions:read`, `tool-sessions:write` | Сессии инструментов |
| `syncs:read`, `syncs:write` | Синхронизации и экспорты |
| `events:read`, `events:write` | События и подписки |

Отсутствующее полномочие даёт `403 capability_missing`. Обычный ключ не получает право изменять чужое подключение только из-за наличия `connections:write`. MCP OAuth не делегирует `connections:manage`.

Интерфейс предназначен для серверного использования. CORS на `/v1`, `/mcp` и compat не включён. Не помещайте bearer-ключ в браузерный код, URL или публичный репозиторий.

## Тела и идентификаторы запросов

JSON передавайте с `Content-Type: application/json`. Лимит входного тела — 65 536 байт. Заголовки и request line ограничены listener; длинный vendor URL может быть отклонён ещё до маршрутизации.

`X-Request-Id` необязателен: допустимы 1–128 символов по шаблону `[A-Za-z0-9][A-Za-z0-9._:-]{0,127}`. Без него сервер создаёт UUID. Некорректное значение отклоняется с `422`; ответ содержит новый безопасный request id. Сохраняйте `X-Request-Id` и execution id для диагностики.

## Идемпотентность и повторы

Передавайте `Idempotency-Key`, когда он объявлен в параметрах метода. Значение: 8–128 символов `[A-Za-z0-9._:-]`. Повтор того же запроса с тем же ключом возвращает исходный результат; изменённое тело с прежним ключом даёт `409 idempotency_conflict`. Для новой намеренной операции выбирайте новый ключ.

`202` при создании execution означает принятие или сохранённый отказ, а не успешное изменение у провайдера. Читайте `status`, `denial_code` и адрес из `Location`, затем опрашивайте execution. Не повторяйте запись автоматически после таймаута: она могла примениться.

Текущий `idempotency_conflict` не различает ещё выполняющийся запрос и несовпадающее тело; `Retry-After` для него не обещан. Сверьте исходный запрос и состояние операции. Mirror API и raw proxy не являются идемпотентными: каждый вызов может отправить новый запрос провайдеру.

## Пагинация

Списки используют непрозрачный `cursor` и `next_cursor`. Передавайте полученный курсор неизменным до `null`; не конструируйте его из ID. Общий `limit` — 1–100, по умолчанию 20; точные параметры и ограничения конкретного метода приведены в справочнике. Курсор ограничен 400 символами. Фильтры сохраняйте одинаковыми между страницами.

Vendor-пагинация — отдельный контракт провайдера: смотрите `paging` в описании endpoint. Существование курсора Context4 не означает автоматический сбор всех страниц upstream.

## Ошибки и лимиты

Ошибка платформы возвращается как `application/problem+json` с `type`, `code`, `title`, `status`, `request_id`. Точные enum и поля: [Problem](https://context4.me/docs/api-schemas-1.md#problem). Внутренние причины и credentials клиенту не передаются.

| HTTP | Действие клиента |
| --- | --- |
| 400 | Исправьте параметры или тело; проверьте схему |
| 401 | Проверьте ключ, срок и отзыв |
| 403 | Проверьте полномочия, владельца, политику и ограничения сессии |
| 404 | Проверьте ID и область доступа |
| 409 | Проверьте конфликт версии, аккаунта или idempotency key |
| 429 | Соблюдайте `Retry-After`, если он возвращён |
| 500 | Сохраните request id для поддержки |
| 503 | Проверьте доступность сервиса; повтор записи требует проверки исхода |

`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` описывают минутное окно API-ключа; reset — число секунд до сброса. При недоступности Redis изменения закрываются с `503`; чтение может продолжиться без rate-limit заголовков. Квота выполнения и лимит HTTP-запросов — отдельные проверки.