---
title: Аутентификация
description: Как авторизовать запросы к Clipia API — API-ключ, три формы заголовка, боевые и тестовые ключи, права доступа и безопасное хранение ключа.
icon: KeyRound
---

Все запросы к `/v1/*` авторизуются API-ключом. Ключ создаётся в консоли разработчика, показывается один раз, привязан к вашему аккаунту и списывает кредиты с его баланса. Рекомендуемый заголовок — `Authorization: Bearer clipia_live_…`.

## Формы заголовка

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

<Tabs items={['Bearer', 'Key', 'X-Api-Key']}>
<Tab value="Bearer">

```bash
curl https://api.clipia.ai/v1/account \
  -H "Authorization: Bearer $CLIPIA_KEY"
```

</Tab>
<Tab value="Key">

```bash
curl https://api.clipia.ai/v1/account \
  -H "Authorization: Key $CLIPIA_KEY"
```

</Tab>
<Tab value="X-Api-Key">

```bash
curl https://api.clipia.ai/v1/account \
  -H "X-Api-Key: $CLIPIA_KEY"
```

</Tab>
</Tabs>

| Форма | Заголовок | Примечание |
|-------|-----------|------------|
| Bearer | `Authorization: Bearer …` | рекомендуется; принимает только ключи с префиксом `clipia_` |
| Key | `Authorization: Key …` | альтернативная схема, слово `Key` можно писать в любом регистре |
| X-Api-Key | `X-Api-Key: …` | если удобнее отдельный заголовок |

## Боевые и тестовые ключи

Префикс ключа определяет среду. Среду вы выбираете при создании ключа.

| Префикс | Среда | Поведение |
|---------|-------|-----------|
| `clipia_live_…` | боевая | реальная генерация, кредиты списываются |
| `clipia_test_…` | песочница | готовый образец сразу, стоимость считается, но не списывается |

Чтобы перейти из песочницы в боевой режим, замените ключ — код менять не нужно. Подробнее — на странице [«Тестовый режим»](/ru/docs/getting-started/sandbox).

<Callout type="warn" title="Боевому ключу нужна активная подписка">
Генерация через API на ключе `clipia_live_` доступна, пока у аккаунта активна подписка. Без неё запрос вернёт `402` с кодом `subscription_required`: покупка пакета кредитов доступ не открывает. Тестовые ключи `clipia_test_` работают без оплаты.
</Callout>

## Как получить ключ

1. Откройте [консоль разработчика](/ru/developer), вкладка **API-ключи**.
2. Нажмите **Создать ключ**, задайте имя (до 100 символов) и выберите среду: боевую или тестовую.
3. Скопируйте ключ и **секрет для подписи вебхуков**. Оба показываются один раз.

На одном аккаунте может быть до 20 активных ключей. Если лимит исчерпан, создание вернёт `400` с сообщением `api_key_limit_reached` — отзовите ненужный ключ и создайте новый.

<Callout type="warn" title="Ключ — серверный секрет">
Не размещайте ключ в браузере, мобильном приложении, фронтенд-бандле или публичном репозитории. Храните его в секрет-менеджере или переменных окружения сервера. Если ключ скомпрометирован, отзовите его в консоли и создайте новый.
</Callout>

**Пароль аккаунта и ключи.** Смена пароля в настройках аккаунта API-ключи не затрагивает, а OAuth-подключения MCP перестают работать до вашего следующего входа в аккаунт Clipia. Сброс пароля по ссылке из письма «Забыли пароль» отзывает все активные ключи и OAuth-подключения: это сценарий восстановления доступа, после него создайте ключи заново и переподключите MCP-клиенты. Если подозреваете утечку ключа, не ждите смены пароля — отзовите ключ в консоли.

## Права ключа [#scopes]

Каждый ключ создаётся с правами `generate` и `read`. Выбирать права при создании не нужно.

| Право | Что разрешает |
|-------|---------------|
| `generate` | создание генераций (`POST /v1/models/{model}`) и LLM-чат [AI Gateway](/ru/docs/llm-gateway) (`POST /v1/chat/completions`) |
| `read` | зарезервировано, сейчас ничего дополнительно не открывает |

- Отдельный ключ для LLM не нужен: право `generate` включает чат. Генерация медиа и LLM списывают кредиты с одного баланса.
- Статус и результат своей генерации может читать любой действующий ключ.
- Каталог моделей (`GET /v1/models`), оценка стоимости и баланс (`GET /v1/account`) доступны без дополнительных прав.
- Запрос без нужного права вернёт `403 insufficient_scope`.

<Callout type="error" title="Ключ не принят">
Если ключа нет, он неверный или отозван, сервер ответит `401 invalid_api_key`. Проверьте префикс среды и то, что ключ передан в одном из трёх заголовков. Схема `Bearer` принимает только ключи, которые начинаются с `clipia_`.
</Callout>