Аккаунт

API-ключи

Используйте API аккаунта Gateway, когда ключами для запросов к моделям нужно управлять программно.

Аутентификация и идемпотентность

Authorization: Bearer YOUR_PROVISIONING_KEY

Каждая мутация требует уникальный Idempotency-Key. Повторно используйте значение только для повтора той же логической операции после неопределённого сетевого результата.

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

curl https://api.makura.ai/v1/account/api-keys -H "Authorization: Bearer YOUR_PROVISIONING_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" -d '{
  "name": "CI worker",
  "spendPolicy": {"limitUnits": "25", "currency": "unit"},
  "loggingPolicy": {
    "storeRequest": false,
    "storeResponse": false,
    "retentionDays": 30
  },
  "modelPolicy": {"mode": "all", "modelIds": []}
}'

Секрет показывается только один раз при создании или ротации. Сразу сохраните его в защищённом хранилище.

Операции

Операция	Эндпоинт	Назначение
Список	`GET /v1/account/api-keys`	Инвентаризация с cursor pagination
Создание	`POST /v1/account/api-keys`	Выпуск нового секрета
Изменение	`PATCH /v1/account/api-keys/{keyId}`	Название, состояние и политики
Ротация	`POST /v1/account/api-keys/{keyId}/rotate`	Новый секрет вместо старого
Отзыв	`POST /v1/account/api-keys/{keyId}/revoke`	Необратимая остановка аутентификации

Изменение, ротация и отзыв требуют текущий expectedVersion. Устаревшая версия возвращает conflict и не перезаписывает конкурентное изменение.

Лимит расходов

spendPolicy.limitUnits задаёт максимальный расход ключа в кредитах. Это не рублёвый лимит: RUB используется кошельком и страницей оплаты, а Gateway применяет кредитную единицу политики ключа.

Создавайте отдельные ключи для рабочего и тестового окружений, разработки и CI. Так проще ограничивать последствия утечки и корректно атрибутировать расходы.

Частые ошибки

передача обычного API-ключа вместо управляющего;
потеря одноразово показанного секрета;
повторное использование одного ключа в несвязанных окружениях;
ротация без обновления всех потребителей.