Персональные API-ключи

Персональный API-ключ - это долгоживущий токен для скриптов, CI и интеграций: в отличие от JWT его не нужно обновлять каждые 15 минут. Ключ привязан к одному рабочему пространству и не даёт доступа к другим workspace того же аккаунта, а набор разрешений (скоупов) задаётся при создании.

Как получить ключ

1. 1

   Откройте раздел ключей

   В панели управления перейдите в «Настройки» → «API-ключи» → вкладка «Персональные ключи»

2. 2

   Нажмите «Создать ключ»

   Укажите название, выберите скоупы и, при необходимости, срок действия

3. 3

   Сохраните ключ сразу

   Скопируйте значение из диалога и положите его в секреты CI

Формат ключа

Ключ состоит из префикса cbk_ и 43 символов случайной части. В списке ключей видно только начало - cbk_XXXXXXXX, по нему удобно отличать ключи друг от друга.

cbk_8s2Kf3nQ1vTzR7pLxYb0WmHc4JdEuG6aNsV9tZoQiRk

Как передавать ключ

Ключ передаётся в том же заголовке Authorization, что и JWT - отдельного заголовка нет. Сервер отличает ключ от токена по префиксу cbk_.

curl -H "Authorization: Bearer cbk_ваш_ключ" \
  https://api.cronbox.ru/v1/workspaces/$WORKSPACE_ID/cron

Создание cron-задачи тем же ключом:

curl -X POST https://api.cronbox.ru/v1/workspaces/$WORKSPACE_ID/cron \
  -H "Authorization: Bearer cbk_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Синхронизация данных",
    "url": "https://your-api.com/sync",
    "method": "POST",
    "schedule": "0 */6 * * *",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"action\": \"sync\"}",
    "timeout_seconds": 30,
    "retry_count": 3
  }'

Скоупы

Ключ может делать только то, что разрешено выданными ему скоупами.

Правило простое: GET-запросы требуют скоуп :read, все остальные методы - :write у соответствующего ресурса.

Если скоупа не хватает, приходит ответ 403:

{
  "detail": {
    "error": "insufficient_scope",
    "message": "API key is missing the required scope",
    "required_scope": "tasks:write"
  }
}

Невалидный, отозванный или просроченный ключ получает 401.

Что ключом сделать нельзя

Часть операций доступна только при входе в панель управления (по JWT). Ключу на них отвечают 403:

• управление аккаунтом и паролем - /v1/auth/*
• биллинг и подписки
• управление воркерами
• создание и удаление рабочих пространств
• управление самими API-ключами

Эндпоинты управления ключами

Доступны только из панели управления, то есть по JWT.

Создание ключа

Поле expires_in_days необязательное: без него ключ бессрочный.

curl -X POST https://api.cronbox.ru/v1/workspaces/$WORKSPACE_ID/api-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI",
    "scopes": ["tasks:read", "tasks:write"],
    "expires_in_days": 90
  }'

Поле key возвращается единственный раз - в ответе на создание:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "CI",
  "key": "cbk_8s2Kf3nQ1vTzR7pLxYb0WmHc4JdEuG6aNsV9tZoQiRk",
  "key_prefix": "cbk_8s2Kf3nQ",
  "scopes": ["tasks:read", "tasks:write"],
  "expires_at": "2024-04-14T10:30:00Z",
  "last_used_at": null,
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z"
}