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

API-ключи пространства Router — как их передавать, их лимиты, срок действия и ротация.

Каждый запрос к `/api/v1`, кроме `GET /api/v1/models`, требует API-ключ в заголовке `Authorization`:

```http
Authorization: Bearer sk-nr-...
```

## API-ключи

API-ключ принадлежит одному пространству Router. Участники с нужной ролью создают ключи на странице **API-ключи** пространства в кабинете. Ключ выглядит так: `sk-nr-<prefix>-<secret>`:

- секрет показывается **один раз**, при создании ключа; роутер хранит только хеш и префикс;
- запросы каждого ключа оплачивает плательщик его пространства, и они видны в логах пространства.

## Настройки ключа

| Настройка            | Что делает                                                                               |
| -------------------- | ---------------------------------------------------------------------------------------- |
| Бюджет               | Сколько ключ может потратить, в PnP. Запрос, который превысил бы бюджет, получает `402`. |
| Сброс бюджета        | Никогда, ежедневно, еженедельно или ежемесячно; сброс происходит в 00:00 по Москве.      |
| Запросов в минуту    | Лимит запросов для этого ключа ниже стандартного.                                        |
| Срок действия        | Дата, после которой ключ перестает работать (`401`). Срок можно продлить.                |
| Отключить / Включить | Приостанавливает ключ без отзыва. Отключенный ключ получает `401`.                       |
| Отозвать             | Удаляет ключ навсегда.                                                                   |

`GET /api/v1/key` возвращает текущие расходы, бюджет, период сброса и срок действия ключа, с которым сделан запрос. См. [GET /key](/docs/ru/api/key).

## Храните ключи в секрете

- Вызывайте API со своего сервера, а не из браузера или мобильного приложения: любой, кто может прочитать страницу, прочитает и ключ. API не отправляет заголовки CORS, поэтому браузеры на других сайтах все равно не смогут его вызвать.
- Храните ключи в переменных окружения или в менеджере секретов, а не в коде и репозиториях.
- Используйте отдельный ключ для каждого приложения или окружения: тогда для него можно задать свой бюджет и отозвать его отдельно.

## Ротация ключа

1. Создайте новый ключ в том же пространстве Router.
2. Разверните его в своем приложении.
3. Проверьте в логах, что запросы идут с новым ключом, затем отзовите старый.

## Ошибки аутентификации

| Статус | Сообщение                                                | Что делать                                      |
| ------ | -------------------------------------------------------- | ----------------------------------------------- |
| `401`  | `invalid API key`                                        | Проверьте заголовок и ключ.                     |
| `401`  | `the API key is disabled` / `has expired` / `is revoked` | Включите или продлите ключ либо создайте новый. |
| `402`  | `the API key spending limit is reached`                  | Увеличьте бюджет или дождитесь сброса.          |
| `403`  | `the Router space has no payer Nodul space`              | Выберите плательщика в настройках пространства. |

Все коды ошибок — в разделе [Ошибки](/docs/ru/errors).