Scopes
Scope - это строка вида <resource>:<action>, которая определяет какие операции разрешены ключу. Назначаются при создании, проверяются на каждый запрос.
Каталог
Заголовок раздела «Каталог»| Scope | Описание |
|---|---|
account:read | Чтение информации об аккаунте (GET /me) и участников аккаунта (GET /members, GET /members/{userId}). |
projects:read | Чтение проектов (GET /projects, GET /projects/{id}). |
projects:write | Создание/изменение проектов. |
tasks:read | Чтение задач (GET /tasks, GET /tasks/{id}). |
tasks:write | Создание, обновление, удаление задач. |
events:read | Чтение событий календаря (GET /events, GET /events/{id}). |
events:write | Создание, обновление, удаление событий. |
attachments:read | Чтение метаданных и скачивание вложений. |
attachments:write | Загрузка и удаление вложений. |
Проверка scope
Заголовок раздела «Проверка scope»При отсутствии требуемого scope сервер возвращает 403 Forbidden с телом:
{ "error": { "code": "insufficient_scope", "message": "Required scope 'tasks:write' is missing" }}Заголовок WWW-Authenticate содержит требуемый scope:
WWW-Authenticate: Bearer error="insufficient_scope", scope="tasks:write"Per-app rate limit (OAuth)
Заголовок раздела «Per-app rate limit (OAuth)»Каждое OAuth-приложение имеет поле rateLimitPerMinute (диапазон 1..500, default 500). Это третий бакет в dual-bucket модели (per-key + per-account + per-oauth-app). При превышении любого бакета сервер возвращает 429 Too Many Requests.
PATCH /api/v1/accounts/{accountId}/oauth-apps/{clientId}{ "rateLimitPerMinute": 100}Приложение автоматически отключается (isDisabled=true) после 100 подряд ответов 429 от бэкенда. Для ручного восстановления:
PATCH /api/v1/accounts/{accountId}/oauth-apps/{clientId}{ "isDisabled": false}Принцип наименьших привилегий
Заголовок раздела «Принцип наименьших привилегий»Выдавайте только те scopes, которые действительно нужны интеграции. Например, для бота, который читает задачи и комментирует - достаточно tasks:read; не давайте tasks:write, если код не пишет.