Автентифікація за API-ключем

Як запит повідомляє, хто він, — API-ключ, єдиний проєкт, у якому ключ діє, і дозволи, що кажуть, що йому можна.

3 хв читання

Кожен запит до API несе API-ключ. Ключ каже, у якому проєкті діє запит і що йому там дозволено.

Ключ

Надсилайте ключ у заголовку Authorization після слова Bearer.

HTTP

Authorization: Bearer sl_live_…

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

Зберігайте ключ там, де ваш сервер зберігає свої секрети. Не розміщуйте його в коді, який виконується в браузері або на пристрої клієнта.

Приклади в цьому довіднику читають ключ зі змінної середовища SLEN_API_KEY.

Terminal

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

200 OK

{
  "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.

Сервісу, який працює з двома проєктами, потрібні два ключі.

Дозволи

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

Дозвіл	Дає також
`read`	—
`gateway:write`	`read`
`management:read`	`customers:read`
`management:write`	`management:read`, `flows:write`, `customers:read`, `customers:write`
`flows:write`	`management:read`, `customers:read`
`customers:read`	—
`customers:write`	`customers:read`

Дозвіл	Для чого він
`read`	Читати те, що робив проєкт, — операції, виконання, авторизації, реєстр, аналітику, каталог моделей
`gateway:write`	Надсилати запити, які можуть витрачати, — запускати флоу
`management:read`	Читати конфігурацію — флоу, підключення й пули провайдерів, клієнтів та їхні кредити
`management:write`	Змінювати конфігурацію й бюджети, поповнювати й коригувати кредити клієнтів, схвалювати або відхиляти те, що чекає рішення
`flows:write`	Створювати, редагувати й публікувати флоу
`customers:read`	Читати ваших клієнтів, їхні рахунки кредитів і виписки, а також ціни в кредитах
`customers:write`	Створювати, поповнювати, списувати, коригувати, блокувати й видаляти ваших клієнтів і змінювати налаштування їхніх рахунків

Деякі дозволи включають інші, і перша таблиця перелічує все, що включає кожен із них. 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 — ключ намагався змінити те, що належить усій організації.

Конверт помилки описано в статті Огляд, а кожен код — у статті Коди помилок.

Зібрано з openapi b070e1f, sdk contract 5cc7055, php ae4a53b, node 84bc62d