Caicaini
Начать

Старт

Аутентификация

Каждый запрос к /v1/* проходит аутентификацию по bearer-токену. Никаких IP-белых списков, подписанных запросов или nonce — только API-ключ Caicaini в заголовке Authorization.

Формат ключа

API-ключи Caicaini начинаются с префикса cai_api_ и содержат 32 случайных символа из URL-безопасного алфавита. Полный ключ показывается один раз при создании и впоследствии получить его нельзя. На нашей стороне в открытом виде хранятся только первые 12 символов (префикс плюс несколько случайных байтов) — их можно отображать в твоём дашборде и в наших логах, не раскрывая секрет.

Остальную часть мы хешируем через argon2id и проверяем за константное время на каждом запросе. На горячем пути есть кеш в Redis на 5 минут, который сводит стоимость проверки практически к нулю.

Заголовок Authorization

Передавай ключ как bearer-токен. Имя заголовка регистронезависимо, но схема — нет: должно быть ровно Bearer, один пробел и сам ключ.

заголовок
Authorization: Bearer cai_api_YOUR_KEY

Проверь свой ключ

Самый дешёвый способ убедиться, что ключ настроен правильно — вызвать GET /v1/account. Эндпойнт возвращает текущий тариф лимитов, доступный баланс кредитов и сколько кредитов потрачено в этом месяце. Модель не запускается, кредиты не списываются.

curl https://caicaini.com/v1/account \
  -H "Authorization: Bearer cai_api_YOUR_KEY"

Что приходит при неудачной аутентификации

Ошибки аутентификации возвращают HTTP 401 в формате ниже. Если заголовок Authorization отсутствует, тело ограничено стандартным конвертом ошибки.

ответ · 401
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key."
  }
}

Полный список типов ошибок и их причин — на странице Ошибки.

Как безопасно хранить ключи

  • Положи ключ в переменную окружения (CAICAINI_API_KEY), в менеджер секретов или в запечатанный конфиг развёртывания. Никогда не коммить его и не отправляй внутри веб-бандла.
  • Ключ аутентифицирует твой аккаунт. Любой, у кого есть ключ, может тратить твои apiCredits до тех пор, пока ты его не отзовёшь.
  • Для браузерных приложений ходи через свой сервер. Браузер не должен видеть ключ.
  • По одному ключу на окружение (dev, staging, prod) и по одному на сервис. Тогда отзыв утёкшего ключа затронет только ту поверхность, откуда он утёк.

Ротация и отзыв

Заходи на /developers/keys, чтобы создавать, смотреть и отзывать ключи. Отзыв срабатывает мгновенно. В той же транзакции инвалидируется и 5-минутный кеш Redis, поэтому отозванный ключ уже через секунды не сможет совершить новый вызов.

Рекомендация: создай новый ключ, выкати его в прод, а затем отзови старый. Активных ключей на аккаунт максимум 25 — если упёрся в лимит, сначала почисти неиспользуемые.

Скоупы

К каждому ключу привязан список скоупов. Дефолтные скоупы новых ключей разработчика — messages.create, models.read и usage.read, этого достаточно для всего, что описано в этом справочнике. Узкие скоупы (только-чтение, только-batch) появятся, когда мы сможем обеспечить их поэлементное соблюдение. До тех пор считай ключ полным доступом к API.

ДалееМодели