Scope’ы описывают, что может делать access-токен OAuth. Запрашивайте только нужные — пользователи видят список на consent-экране и охотнее авторизуют короткий список.
Неявный scope
| Scope | Выдаётся автоматически | Описание |
|---|---|---|
user.read | да | Чтение id, имени, email и аватара авторизованного пользователя + текущий workspace. Используется /oauth/userinfo. |
user.read не нужно включать в scope — он выдаётся всегда.
Доступные scope’ы
Для каждого ресурса — .read (только чтение) или .write (чтение + запись). Write-scope всегда включает соответствующее read-разрешение.
Links
| Scope | Даёт |
|---|---|
links.read | Получение/поиск списков и метаданных коротких ссылок |
links.write | Создание, обновление, архивирование и удаление ссылок |
Tags
| Scope | Даёт |
|---|---|
tags.read | Список и получение тегов |
tags.write | Создание, переименование и удаление тегов |
Folders
| Scope | Даёт |
|---|---|
folders.read | Список папок и их настроек |
folders.write | Создание, обновление и удаление папок |
Domains
| Scope | Даёт |
|---|---|
domains.read | Список доменов и их DNS/SSL-статус |
domains.write | Добавление, верификация, настройка и удаление кастомных доменов |
Analytics
| Scope | Даёт |
|---|---|
analytics.read | Чтение агрегированной аналитики (клики, лиды, продажи, топ-страны/устройства и т.д.) и потока событий |
analytics.write не существует — аналитика производится платформой, а не пишется через API.
Webhooks
| Scope | Даёт |
|---|---|
webhooks.read | Список вебхуков и их подписок на события |
webhooks.write | Создание, обновление, ротация и удаление вебхуков |
Выбор scope’ов
Несколько рекомендаций:
- Read-only интеграции (Notion sidebar, dashboard widget) — только
*.readscope’ы. - Утилиты создания ссылок (расширение для браузера, Slack-команда
/shorten) — обычно достаточноlinks.write. - Полная замена платформы (кастомный дашборд) — комбинируйте
links.write,analytics.read,tags.write,folders.write,domains.read. - Мастера настройки вебхуков — только
webhooks.write.
Избегайте domains.write, если только реально не управляете кастомными доменами пользователей — он позволяет удалять домены, что может сломать ссылки всего workspace.
Проверка выданных scope’ов
Ответ token-эндпоинта содержит фактически выданные пользователем scope’ы (может быть подмножеством запрошенного):
{
"access_token": "dub_access_token_...",
"expires_in": 7200,
"refresh_token": "...",
"scope": "links.read links.write analytics.read"
}Всегда проверяйте scope перед вызовом API — не предполагайте, что пользователь выдал всё запрошенное.
Изменение scope’ов для уже авторизовавшегося пользователя
Scope’ы фиксируются в момент авторизации. Чтобы запросить дополнительные у уже авторизованного пользователя — отправьте его снова на /oauth/authorize с новым списком scope’ов. RevRoute покажет свежий consent-экран только с новыми scope’ами и, при одобрении, выдаст токены, объединяющие старые и новые разрешения.
Персональные API-ключи
Для сравнения, workspace API-ключи имеют более широкий список scope’ов, включая write-разрешения для аналитики и настроек workspace. OAuth-приложения намеренно ограничены списком выше — если вам нужно что-то ещё, OAuth не подходящий инструмент.