← Cloudflare Fundamentals / fundamentals / api / how-to
URL-адреса шаблонов API-токенов
Используйте URL-шаблоны, чтобы создавать API-токены Cloudflare с заранее настроенными разрешениями. URL-шаблоны позволяют передавать пользователям требования к токену без необходимости вручную выбирать разрешения в панели управления.
Template URL использует параметры запроса для предварительного заполнения страницы создания API-токена в панели управления Cloudflare. Когда пользователь открывает такую ссылку, панель управления автоматически настраивает указанные разрешения и параметры.
Cloudflare поддерживает шаблонные URL как для пользовательские API-токены и API-токены аккаунта. Подробнее о различиях между этими типами токенов см. в Токены API аккаунта.
Формат URL пользовательского токена
URL-шаблоны пользовательского токена открывают форму создания токена на уровне профиля пользователя (/profile/api-tokens). Токены, созданные таким образом, принадлежат пользователю.
Базовая структура Template URL:
https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=[ENCODED_PERMISSIONS]&accountId=*&zoneId=all&name=[TOKEN_NAME]Компоненты URL
| Параметр | Обязательный | Описание |
|---|---|---|
permissionGroupKeys |
Да | JSON-массив объектов разрешений в кодировке URL |
accountId |
Да | Область аккаунта (используйте * для всех аккаунтов) |
zoneId |
Да | Область действия зоны (используйте all для всех зон) |
name |
Нет | Предзаполненное имя токена |
Формат URL-адреса токена аккаунта
Шаблонные URL-адреса токена аккаунта открывают форму создания токена на уровне аккаунта. Токены, созданные таким способом, принадлежат аккаунту (токены service principal) и не привязаны к конкретному пользователю. Для создания токенов аккаунта требуются права Super Administrator или Administrator.
Базовая структура Template URL:
https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=[ENCODED_PERMISSIONS]&name=[TOKEN_NAME] :account сегмент является заполнителем. Когда пользователь открывает URL, дашборд предлагает ему выбрать аккаунт, если у него есть доступ к нескольким.
Компоненты URL
| Параметр | Обязательный | Описание |
|---|---|---|
permissionGroupKeys |
Да | JSON-массив объектов разрешений в кодировке URL |
name |
Нет | Предзаполненное имя токена |
Формат разрешения
Шаблоны URL как для токенов пользователя, так и для токенов аккаунта используют одинаковую кодировку разрешений. Разрешения кодируются в виде массива JSON со следующей структурой:
[{ "key": "permission_name", "type": "read|edit|revoke|run|purge" }]Типы разрешений
| Тип | Описание |
|---|---|
read |
Доступ только для чтения |
edit |
Полный доступ (создание, чтение, обновление, удаление) |
revoke |
Отзыв разрешений |
run |
Разрешения на выполнение |
purge |
Разрешения на очистку кэша |
Создание пользовательских шаблонов
1. Определите необходимые разрешения
Перечислите разрешения, необходимые для вашего сценария использования. См. раздел справочник по правам доступа в таблице.
2. Создайте JSON с разрешениями
Оформите свои разрешения в виде массива JSON:
[
{ "key": "dns", "type": "edit" },
{ "key": "analytics", "type": "read" }
]3. Выполните URL-кодирование JSON
Используйте URL-кодировщик, чтобы преобразовать JSON-строку:
%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%5D4. Постройте полный URL
Для пользовательский токен, объедините все компоненты в итоговый URL шаблона:
https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=[ENCODED_JSON]&accountId=*&zoneId=all&name=Custom%20TokenДля токен аккаунта, вместо этого используйте путь уровня аккаунта:
https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=[ENCODED_JSON]&name=Custom%20TokenСправочник по разрешениям
Используйте эту таблицу, чтобы найти ключи разрешений для своих пользовательских шаблонов.
Разрешения аккаунта
| Ключ разрешения | Описание | Типичные варианты использования |
|---|---|---|
account_analytics |
Аналитика аккаунта | Отчетность, мониторинг |
account_api_tokens |
Управление API-токенами | Автоматизация токенов |
account_settings |
Настройка аккаунта | Управление аккаунтом |
billing |
Платежная информация | Учёт затрат, выставление счетов |
workers_scripts |
скрипты Workers | Бессерверные функции |
workers_kv_storage |
хранилище Workers KV | Хранение данных |
workers_routes |
Workers routes | Маршрутизация трафика |
workers_r2 |
Хранилище R2 | Объектное хранилище |
d1 |
База данных D1 | Базы данных SQL |
queues |
Queues | Очередь сообщений |
page |
Cloudflare Pages | Развертывания Pages |
stream |
Stream | Потоковое воспроизведение видео |
images |
Изображения | Оптимизация изображений |
logs |
Журналы | Управление логами |
Разрешения зоны
| Ключ разрешения | Описание | Типичные варианты использования |
|---|---|---|
dns |
DNS-записи | Управление доменами |
zone |
Управление зоной | Настройка доменов |
zone_settings |
Настройки зоны | Конфигурация зоны |
analytics |
Аналитика зоны | Мониторинг производительности |
firewall_services |
Правила Firewall | Управление безопасностью |
page_rules |
Page rules | Управление трафиком |
cache |
Очистка кеша | Обновления содержимого |
ssl_and_certificates |
Сертификаты SSL/TLS | Управление сертификатами |
Разрешения Access
| Ключ разрешения | Описание | Типичные варианты использования |
|---|---|---|
access |
Приложения Access | Приложения Zero Trust |
access_acct |
Организации Access | Управление удостоверениями |
access_audit_log |
Доступ к журналам аудита | Соответствие требованиям, безопасность |
access_custom_page |
Custom pages | Брендинг, пользовательский опыт |
teams |
Zero Trust | Gateway, CASB, DLP |
Распространенные шаблоны прав доступа
Используйте эти готовые URL-шаблоны для типичных сценариев. Каждый пример включает URL как для пользовательского токена, так и для токена аккаунта.
Управление DNS
Создание токенов для управления DNS-записями.
Пользовательский токен
| Сценарий использования | Template URL |
|---|---|
| DNS только для чтения | https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22read%22%7D%5D&accountId=%2A&zoneId=all&name=DNS%20Read%20Token |
| DNS для чтения и записи | https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22edit%22%7D%5D&accountId=%2A&zoneId=all&name=DNS%20Management%20Token |
Токен аккаунта
| Сценарий использования | Template URL |
|---|---|
| DNS только для чтения | https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22read%22%7D%5D&name=DNS%20Read%20Token |
| DNS для чтения и записи | https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22edit%22%7D%5D&name=DNS%20Management%20Token |
Разработка на Workers
Создание токенов для Workers, KV storage и смежных сервисов.
Пользовательский токен
| Сценарий использования | Template URL |
|---|---|
| только скрипты Workers | https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%5D&accountId=%2A&zoneId=all&name=Workers%20Scripts%20Token |
| Полный доступ к Workers | https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22workers_kv_storage%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22workers_routes%22%2C%22type%22%3A%22edit%22%7D%5D&accountId=%2A&zoneId=all&name=Workers%20Full%20Access%20Token |
Токен аккаунта
| Сценарий использования | Template URL |
|---|---|
| только скрипты Workers | https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%5D&name=Workers%20Scripts%20Token |
| Полный доступ к Workers | https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22workers_scripts%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22workers_kv_storage%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22workers_routes%22%2C%22type%22%3A%22edit%22%7D%5D&name=Workers%20Full%20Access%20Token |
Аналитика и мониторинг
Создание токенов для доступа к аналитике и журналам.
Пользовательский токен
| Сценарий использования | Template URL |
|---|---|
| Аналитика аккаунта | https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22account_analytics%22%2C%22type%22%3A%22read%22%7D%5D&accountId=%2A&zoneId=all&name=Account%20Analytics%20Token |
| Аналитика зоны | https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%5D&accountId=%2A&zoneId=all&name=Zone%20Analytics%20Token |
Токен аккаунта
| Сценарий использования | Template URL |
|---|---|
| Аналитика аккаунта | https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22account_analytics%22%2C%22type%22%3A%22read%22%7D%5D&name=Account%20Analytics%20Token |
| Аналитика зоны | https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%5D&name=Zone%20Analytics%20Token |
Администрирование Zero Trust
Создание токенов для управления Cloudflare Zero Trust.
Пользовательский токен
| Сценарий использования | Template URL |
|---|---|
| Access applications read | https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22access%22%2C%22type%22%3A%22read%22%7D%5D&accountId=%2A&zoneId=all&name=Access%20Read%20Token |
| Полное управление Access | https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%7B%22key%22%3A%22access%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22access_acct%22%2C%22type%22%3A%22edit%22%7D%5D&accountId=%2A&zoneId=all&name=Access%20Management%20Token |
Токен аккаунта
| Сценарий использования | Template URL |
|---|---|
| Access applications read | https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22access%22%2C%22type%22%3A%22read%22%7D%5D&name=Access%20Read%20Token |
| Полное управление Access | https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=%5B%7B%22key%22%3A%22access%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22access_acct%22%2C%22type%22%3A%22edit%22%7D%5D&name=Access%20Management%20Token |
Рекомендации
Следуйте этим рекомендациям при создании и передаче URL-адресов шаблонов.
- Принцип минимальных привилегий: запрашивайте только те разрешения, которые необходимы для вашей задачи. Это снижает риски безопасности в случае компрометации токена.
- Используйте понятные имена токенов: указывайте чёткие, понятные имена в URL-шаблонах, чтобы пользователям было ясно назначение токена.
- Документируйте использование токенов: чётко описывайте, для чего используется каждый токен и как его отозвать, когда он больше не нужен.
- Регулярная смена токенов: рекомендуйте пользователям регулярно обновлять токены и проверять права доступа.
- Проверка перед тем, как поделиться: всегда тестируйте Template URL в тестовой среде (staging), прежде чем предоставлять их пользователям.
Устранение неполадок
Ознакомьтесь со списком типичных проблем и способов их решения.
| Issue | Решение |
|---|---|
| URL не подставляет разрешения автоматически | Убедитесь, что JSON корректно закодирован в формате URL-encoded |
| Отсутствуют разрешения | Проверьте ключи разрешений в справочной таблице |
| Имя токена не отображается | Убедитесь, что параметр name имеет URL-кодировку |
| Ошибка «Доступ запрещён» | Убедитесь, что у пользователя есть необходимые права в его аккаунте |
Кроме того, перед тем как поделиться URL-адресом шаблона, ознакомьтесь с чек-листом.
- Все ключи разрешений указаны верно
- Синтаксис JSON корректен
- URL-кодирование выполнено корректно
- Имя токена содержательное
- Разрешения соответствуют принципу минимальных привилегий