Аутентификация по API-ключу

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

Ключ

Отправляйте ключ в заголовке Authorization после слова Bearer.

Authorization: Bearer sl_live_…

Ключ начинается с sl_live_. Ключ, выпущенный до того, как префикс стал sl_live_, начинается с sg_live_ и продолжает работать. Вы видите его один раз — при выпуске или ротации, — потому что Slen хранит только его хэш. Ключи выпускаются на странице ключей — по шагам это описано в статье Управление API-ключами.

Храните ключ там, где ваш сервер хранит свои секреты. Не помещайте его в код, который выполняется в браузере или на устройстве клиента.

Примеры в этом справочнике читают ключ из переменной окружения SLEN_API_KEY.

curl https://api.slen.ai/api/v1/models \
  -H "Authorization: Bearer $SLEN_API_KEY"

{
  "data": [
    {
      "model_code": "gpt-4o-mini",
      "provider": "openai",
      "model_price_id": "1108",
      "input_price_per_million": "0.15000000",
      "output_price_per_million": "0.60000000",
      "cached_input_price_per_million": "0.07500000",
      "max_output_tokens": 16384,
      "currency": "USD",
      "effective_from": "2026-01-01T00:00:00+00:00",
      "effective_to": null
    }
  ]
}

Две проверки состояния, /health и /ready, — единственные пути, которым ключ не нужен.

Что доступно ключу

Ключ принадлежит одному проекту одной организации и действует только в этом проекте.

• То, что создаёт ключ, создаётся в его проекте. Список отвечает строками его проекта.

• Строка другого проекта или другой организации отвечает 404 — точно так же, как строка, которой не существует.

• То, что организация делит между своими проектами, ключом можно прочитать и нельзя изменить. Попытка отвечает 403 с кодом project_access_restricted.

Сервису, который работает с двумя проектами, нужны два ключа.

Разрешения

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

Некоторые разрешения включают другие, и первая таблица перечисляет всё, что включает каждое из них. management:write включает management:read, flows:write, customers:write и customers:read. Оно не включает read, поэтому ключ, у которого есть только management:write, не может вызвать операцию, требующую read.

Давайте ключу те разрешения, которые нужны его сервису, и не больше. Сервису, который только отправляет запросы, нужно gateway:write. Приложению, которое ещё и ведёт своих клиентов, — добавляет их, пополняет, списывает с них и блокирует, — нужны gateway:write и customers:write, и больше ничего оно с ними не меняет.

Когда запрос отклонён

• 401 с кодом invalid_api_key — в запросе нет ключа, такого ключа не существует или он отозван. Так же ключ после ротации отвечает на свой старый секрет.

• 403 с кодом insufficient_scope — ключ действителен, но не несёт разрешения, которого требует операция. error.message называет недостающее разрешение.

• 403 с кодом project_access_restricted — ключ пытался изменить то, что принадлежит всей организации.

Конверт ошибки описан в статье Обзор, а каждый код — в статье Коды ошибок.