---
title: Аутентификация
description: Один ключ, заголовок, который его несёт, и три вещи, которые платформа помнит о ключе: как он называется, чем оплачивается и до чего ему разрешено дотягиваться.
keywords: аутентификация, bearer, authorization, api-ключ, x-api-key, 401
group: get-started
---

## Быстро {#quick keywords="быстро, заголовок, bearer, x-api-key"}

Ключ едет в одном заголовке, и этого достаточно для всей поверхности:

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

curl https://api.kumorouter.com/v1/chat/completions \
  -H "Authorization: Bearer $KUMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "max_tokens": 16,
    "messages": [{ "role": "user", "content": "reply with OK" }]
  }'
```

:::note
Клиенты и SDK Anthropic шлют ключ иначе — голым, в заголовке `x-api-key`. Обе операции в нативной форме Anthropic принимают его так же, как bearer-заголовок, поэтому такому клиенту достаточно поменять адрес и ключ.
:::

> [Первый вызов целиком →](/ru/quickstart) [Проверить ключ →](/ru/key-check)

## Заголовок {#bearer-header keywords="bearer, authorization, заголовок, токен"}

Ключ едет как bearer-токен в заголовке `Authorization` и больше нигде — ни в строке запроса, ни в куке, ни в теле. Строка запроса оседает в логах доступа и в истории браузера; заголовок — нет.

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

```bash title=Оболочка
# Держите ключ в окружении, а не в исходниках.
export KUMO_API_KEY="kumo_sk_..."

# Каждый вызов несёт его в одном заголовке и больше нигде.
curl https://api.kumorouter.com/v1/chat/completions \
  -H "Authorization: Bearer $KUMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "max_tokens": 16,
    "messages": [{ "role": "user", "content": "reply with OK" }]
  }'
```

> [Весь вызов целиком →](/ru/quickstart)

## Носитель Anthropic {#anthropic-header keywords="x-api-key, anthropic, sdk, messages"}

Две операции в нативной форме Anthropic — `POST /v1/messages` и `POST /v1/messages/count_tokens` — принимают для того же ключа второй носитель: ключ передаётся без обёртки в заголовке `x-api-key`, а заголовка `Authorization` при этом нет вовсе. Это носитель нативного API Anthropic и потому единственный, который шлют его SDK: клиент, написанный под тот API, аутентифицируется здесь без единой правки.

Заголовок объявлен на этих двух операциях и больше нигде: это носитель тех клиентов, а не второй вход в остальную поверхность. Передать оба заголовка законно. Если они расходятся, отказа за это не будет: аутентифицирует присутствующий и корректно оформленный `Authorization`, а голый заголовок не читается вовсе. Сервер, выбирающий между двумя секретами, гадал бы, какой из них вы имели в виду. Сам ключ, поиск за ним и единственный отказ ниже остаются теми же, что у bearer-заголовка.

:::code-group
```bash title=curl
curl https://api.kumorouter.com/v1/messages \
  -H "x-api-key: $KUMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "max_tokens": 128,
    "messages": [{ "role": "user", "content": "Объясни токены одной строкой." }]
  }'
```
```python title=Python
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.kumorouter.com",
    api_key=os.environ["KUMO_API_KEY"],
)

answer = client.messages.create(
    model="<model>",
    max_tokens=128,
    messages=[{"role": "user", "content": "Объясни токены одной строкой."}],
)
print(answer.content[0].text)
```
:::

## Как выглядит ключ {#key-shape keywords="префикс, kumo_sk, секрет, маска, ротация"}

:::deflist
| Свойство | Значение |
| --- | --- |
| Префикс | **kumo_sk_** |
| Показ | один раз, на экране создания |
| Хранение | хэш, плюс префикс и хвост для показа |
:::

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

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

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

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

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

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

> [Выпустить ключ →](https://console.kumorouter.com/) [Прочитать ключ →](/ru/key-check)

## До чего дотягивается ключ {#key-scope keywords="область, модальность, модель, провайдер, привязка"}

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

| член | что это |
| --- | --- |
| `modality_codes` | Какие виды работы можно запрашивать ключом — генерация текста, эмбеддинги, генерация изображений. |
| `model_ids` | Конкретные модели, которые можно называть ключом, когда его нужно ограничить точнее модальности. |
| `vendor_ids` | Провайдеры за этими моделями — для ключа, привязанного к одному из них. |
| `binding` | Исходная привязка ключа, заданная при создании; дальше она неизменна. Тратит ли ключ из пакета аккаунта или с баланса, выбирается отдельно — в консоли, и этот выбор можно менять. |

Вызов, назвавший что-либо вне этих списков, отклоняется, а не маршрутизируется: область — это белый список, а не предпочтение. Что вообще можно назвать, перечислено в [прайс-листе](https://kumorouter.com/ru/pricing), а идентификаторы, которые несёт шлюз, он назовёт сам по адресу `https://api.kumorouter.com/v1/models`.

## Один отказ, и только один {#one-refusal keywords="401, отказ, оракул"}

Любой отказ в предъявлении — это один и тот же 401. Одинаково отвечаются пять случаев:

- заголовка нет вовсе;
- ключ искажён;
- ключ неизвестен;
- ключ отозван;
- срок ключа истёк.

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

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

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