Ключи

Выпустите ключ за минуту

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

export KUMO_API_KEY="kumo_sk_..."

Открыть консоль → Проверить, что ключ живой →

Что выбирается при создании

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

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

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

Белые списки

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

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

Потолки

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

Какие потолки и что делать на 429 → Как область выглядит в ответе →

Секрет показывается один раз

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

Как ключ выглядит в списке

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

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

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

Что меняется после создания

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

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

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

Конец жизни

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

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

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

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

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

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

Что отвечает нерабочий ключ

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

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

Проверить ключ → Все статусы шлюза →