API-ключи

API-ключи — это учётные данные программной поверхности. Они принадлежат воркспейсу и несут список скоупов.

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

curl -b cookies.txt -X POST https://api.runne.run/v1/workspaces/WORKSPACE_ID/api-keys \
  -H 'Content-Type: application/json' \
  -d '{"name":"prod-key","scopes":["chat:write","balance:read"]}'

Тело запроса:

Поле	Тип	Обязательно	Примечания
name	string	да	мин. 1 символ
scopes	string[]	да	мин. 1 элемент
rate_limit	object	нет	{requests_per_minute, tokens_per_day} — оба положительные целые

Если rate_limit не указан, применяются значения по умолчанию: requests_per_minute: 60 и tokens_per_day: 1000000.

Ответ (HTTP 201):

{
  "id": "0191…",
  "raw_key": "rn_live_4xK9mP2qR7sT_7hJ3kL9mN2pQ5rT8vW1xY4zA6bC0dE2fG4hI6jK8",
  "key_id": "4xK9mP2qR7sT",
  "name": "prod-key",
  "scopes": ["chat:write", "balance:read"],
  "created_at": "…"
}

Список ключей

curl -b cookies.txt https://api.runne.run/v1/workspaces/WORKSPACE_ID/api-keys

{
  "api_keys": [
    {
      "id": "0191…",
      "key_id": "4xK9mP2qR7sT",
      "name": "prod-key",
      "scopes": ["chat:write", "balance:read"],
      "created_at": "…",
      "last_used_at": "…",
      "revoked_at": null
    }
  ]
}

В ответе списка никогда нет исходного секрета — только публичный key_id.

Отзыв ключа

curl -b cookies.txt -X DELETE https://api.runne.run/v1/workspaces/WORKSPACE_ID/api-keys/API_KEY_ID

Ответ:

{ "success": true }

Отзыв устанавливает revoked_at. Отозванный ключ отклоняется шлюзом (401 invalid or revoked API key) на следующем же запросе. Отзыв несуществующего или чужого ключа возвращает 404.

Матрица скоупов

Ключ работает на эндпоинте только если несёт требуемый скоуп. В таблице указано, что сервер применяет на самом деле.

Эндпоинт	Требуемый скоуп	Применяется?
POST /v1/chat/completions	chat:write	да
GET /v1/balance	balance:read	да
GET /v1/models	models:read	нет — каталог публичный

models:read не применяется

GET /v1/models (и GET /v1/models/{provider}/{model}) сейчас не требуют аутентификации, поэтому models:read — зарезервированный скоуп без enforcement. В beta считайте каталог публичным.

Выдавайте клиенту минимум скоупов. Ключ только с balance:read не может вызывать chat completions, и наоборот.

Безопасность raw-ключа

raw_key возвращается ровно один раз, при создании. Сервер хранит только HMAC-SHA256(secret) и не может восстановить исходное значение.

• Храните ключ в secrets-менеджере; никогда в системе контроля версий или логах.
• Никогда не выводите raw_key в логи или сообщения об ошибках.
• Ротация — через отзыв старого ключа и создание нового (ротация на стороне клиента) либо через ротацию серверных секретов (API_KEY_SERVER_SECRET / _PREV) для плавной ротации на стороне сервера — см. Аутентификация.
• Пересоздавайте, а не «восстанавливайте»: эндпоинта «показать raw-ключ» нет по замыслу.

Связанное

• Аутентификация — формат ключа и проверка.
• Лимиты и квоты — лимиты на ключ.