---
title: Ключи
description: Вся жизнь ключа: что выбирается при создании и уже не меняется, один показ секрета, выключение, корзина и стирание навсегда.
keywords: ключи, api-ключ, секрет, срок действия, белый список, корзина, отзыв, выключить
group: account
---

## Выпустите ключ за минуту {#quick keywords="создать ключ, скопировать, переменная окружения"}

:::steps
- **Создайте ключ** — На экране ключей в консоли. Название и, если нужно, срок; остальное можно оставить как есть.
- **Скопируйте секрет сразу** — Он показан один раз, на той же панели, которая его создала.
- **Положите его в окружение** — Не в исходники и не в конфиг, который уедет в репозиторий.
:::

```bash title=Оболочка
export KUMO_API_KEY="kumo_sk_..."
```

> [Открыть консоль →](https://console.kumorouter.com/) [Проверить, что ключ живой →](/ru/key-check)

## Что выбирается при создании {#create keywords="название, срок действия, тратит из, белый список, пакет, баланс"}

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

:::deflist
| Свойство | Правило |
| --- | --- |
| Название | От 1 до 50 символов после обрезки пробелов. Считается в символах, поэтому кириллическое название длиной 50 проходит целиком. **Фиксируется при создании.** |
| Срок действия | «Бессрочно» либо один из готовых сроков: 1 час, 1 день, 7, 30, 90, 180 дней, 1 год. **Меняется потом.** |
| Тратит из | Пакет аккаунта или баланс организации. **Меняется потом** — в окне «Выбор способа списания». |
| Белые списки | Модальности, модели, провайдеры. **Фиксируются при создании.** |
:::

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

Название не переименовывается — операции переименования у ключа нет вовсе, и настройки говорят это словами. Белые списки не редактируются по той же причине: лечится это не правкой, а новым ключом с нужным списком и отзывом старого.

:::note
Консоль сегодня создаёт ключ **открытым по всем трём осям**: полей белых списков в форме создания пока нет, хотя сам ключ их несёт. Пока их нет, ключ, созданный в консоли, дотягивается до всего, что опубликовано. Тратит новый ключ из пакета аккаунта, если пакет есть, а иначе — с баланса.
:::

### Белые списки

У ключа есть необязательная область по трём осям, и пустая ось означает «все»: ключ без единой оси ничем не ограничен. Вызов, назвавший что-либо вне списка, отклоняется, а не маршрутизируется, — это белый список, а не предпочтение.

- **Модальности** — виды работы: генерация текста, эмбеддинги, генерация изображений.
- **Модели** — конкретные идентификаторы, по одному в строке.
- **Провайдеры** — поставщики за этими моделями.

### Потолки

Потолки темпа задаёт Kumo, и они стоят на ключе с момента его создания. Ни эта форма, ни любой другой экран консоли их не задаёт — консоль их показывает.

> [Какие потолки и что делать на 429 →](/ru/limits) [Как область выглядит в ответе →](/ru/authentication)

## Секрет показывается один раз {#secret keywords="секрет, показ, хэш, потеря ключа"}

Полный секрет показывает **только та операция, которая ключ создала**, и только в момент создания. Дальше платформа держит его хэш вместе с двумя фрагментами для показа, и прочитать секрет не может ничто: ни экран, ни операция, ни обращение в поддержку.

:::warning
Повтор того же создания с тем же идентификатором попытки вернёт метаданные ключа и **не вернёт секрета**: он не показывается второй раз и не выписывается заново. Лекарство от потерянного ключа — новый ключ.
:::

## Как ключ выглядит в списке {#list keywords="префикс, хвост, версия, статус, расход"}

Список отдаёт метаданные и ничего кроме: ни секрета, ни хэша. Ключ узнают по **первым восьми символам случайной части и последним четырём** плюс по названию, которое вы ему дали, — в списке он и напечатан этими двумя фрагментами с многоточием между ними.

| Колонка | Что показывает |
| --- | --- |
| `Название` | То, что вы задали при создании. |
| `Ключ` | Префикс и хвост — те самые фрагменты, которые безопасно показывать. |
| `Списание` | Пакет аккаунта или баланс организации. |
| `Расход` | Списанное этим ключом с начала текущего месяца по UTC. |
| `Лимит` | Действующие потолки ключа. |
| `Проект` | Ярлык, под которым ключ лежит, или его отсутствие. |

У ключа есть ещё **версия** — она не колонка списка, а свойство строки. Это тот самый номер, с которым сверяется правка: два одновременных изменения не могут выиграть оба, и проигравший получает отказ вместо тихой перезаписи. Версия растёт при изменении метаданных и намеренно не растёт от использования ключа.

Есть ещё **время последнего использования**. Оно приблизительно по построению — значение записывается с задержкой и счётчиком запросов не является.

## Что меняется после создания {#edit keywords="срок, проект, выключить, включить, пакет, баланс"}

Четыре вещи, и все четыре обратимы.

- **Срок действия** — ставится, сдвигается и снимается. Прошедший момент не принимается: ключ нельзя отредактировать так, чтобы он уже был мёртв.
- **Проект** — ключ переносится в проект и выносится из него. Проект — это ярлык и никогда не контейнер денег, поэтому перенос не трогает то, из чего ключ тратит.
- **Из чего тратит** — пакет аккаунта или баланс, а для ключа на пакете ещё и что делать, когда лимит кончится: остановиться или продолжить с баланса. Там же задаются свои лимиты пакета для ключа. Всё это — в окне «Выбор способа списания», которое открывается нажатием на ячейку ключа в колонке «Списание».
- **Выключатель** — «Выключить» и «Включить». Выключенный ключ не аутентифицирует ничего, пока выключен, и не теряет ничего больше.

Выключатель независим от отзыва и не является вторым его написанием: включение снимает только выключатель, а отозванный или просроченный ключ остаётся ровно настолько же мёртв, насколько был.

## Конец жизни {#end-of-life keywords="выключить, корзина, восстановить, стереть, просрочен, отзыв"}

Четыре состояния, в которых ключ не работает. Два из них обратимы, два нет, и путать их дорого.

:::matrix
| Что произошло | Ключ работает | Обратимо |
| --- | --- | --- |
| Выключен | нет | да, «Включить» |
| В корзине | нет | да, «Восстановить» |
| Просрочен | нет | нет |
| Стёрт навсегда | нет | нет |
:::

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

**Стирание навсегда** доступно только для ключа, который уже в корзине; ключ не в корзине оно отвергает. После него ни один список этой поверхности ключа не вернёт.

:::warning
Ни удаление в корзину, ни стирание навсегда не переспрашивают: и то и другое срабатывает с одного нажатия. Обратимо из них только первое.
:::

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

**Просрочка** окончательна: продлить просроченный ключ или снять с него срок нельзя — выпускается новый.

Есть и пятое состояние, терминальное: **отзыв**. Он завершает жизнь ключа, и запись об этом остаётся в журнале вместе с причиной; реактивации нет, и два одновременных отзыва не могут выиграть оба. В консоли отдельной кнопки отзыва нет — там выключатель и корзина. А в списке отозванный ключ и выключенный читаются одним словом: для читателя это одно состояние «не работает, но строка на месте».

## Что отвечает нерабочий ключ {#refusals keywords="401, отказ, отозван, истёк, оракул"}

Один и тот же `401` и одна и та же фраза — на отсутствующий заголовок, искажённый ключ, неизвестный, отозванный, выключенный и истёкший. Шлюз никогда не говорит, что из шести это было: различать их значило бы превратить его в оракул по ключевому материалу.

Какой из ваших ключей жив — вопрос к консоли и к эху личности, а не к шлюзу.

> [Проверить ключ →](/ru/key-check) [Все статусы шлюза →](/ru/errors)