> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voodoo.center/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voodoo.center/_mcp/server.

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

Аутентификация в API Voodoo Center — это процесс с двумя учётными данными:

1. Долгоживущий **API-ключ** (`ak_...`), который вы создаёте и которым управляете
   в дашборде.
2. Короткоживущий **токен доступа** (Bearer JWT), который вы получаете, обменяв
   API-ключ, и отправляете в каждом запросе к API.

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

## 1. Создание API-ключа

В дашборде откройте страницу **API** и создайте ключ.

* Сырой ключ показывается **один раз**, при создании, в формате `ak_...`.
  Скопируйте его сразу и сохраните в надёжном месте — он хешируется на стороне
  сервера и не может быть восстановлен.
* Вы можете создавать, просматривать и **отзывать** ключи на той же странице.
  Отзыв ключа немедленно блокирует любые новые обмены на токены по нему (уже
  выданные токены остаются действительными до истечения срока).

Относитесь к ключу `ak_` как к паролю. Если он утёк, отзовите его в дашборде и
создайте новый.

## 2. Обмен ключа на токен доступа

Отправьте свой ключ (`POST`) на эндпоинт токенов. Ответ содержит `access_token`,
действительный **2 часа** (он несёт `origin=api`).

```bash title="Обмен API-ключа на токен"
curl -X POST https://api.voodoo.center/api/v1/auth/token/client \
  -H "Content-Type: application/json" \
  -d '{"api_key":"ak_your_api_key_here"}'
```

```python title="exchange_key.py"
import httpx

resp = httpx.post(
    "https://api.voodoo.center/api/v1/auth/token/client",
    json={"api_key": "ak_your_api_key_here"},
)
resp.raise_for_status()
access_token = resp.json()["access_token"]
```

```json title="Ответ"
{
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
  "token_type": "Bearer"
}
```

Если ключ неизвестен или отозван, вы получите `401` с `{"error": "Invalid
credentials"}`. Если аутентификация по API-ключу не включена для домена вашего
аккаунта, вы получите `403`.

## 3. Вызов API с токеном

Отправляйте токен в заголовке `Authorization` как Bearer-учётные данные в каждом запросе:

```bash title="Аутентифицированный запрос"
curl https://api.voodoo.center/api/v1/account/balance \
  -H "Authorization: Bearer <access_token>"
```

```python title="authenticated_request.py"
import httpx

resp = httpx.get(
    "https://api.voodoo.center/api/v1/account/balance",
    headers={"Authorization": f"Bearer {access_token}"},
)
resp.raise_for_status()
print(resp.json())  # {"balance": 1240.75}
```

## Срок действия токена и обновление

Срок действия токенов доступа истекает через **2 часа** после их выдачи. Токена
обновления (refresh token) нет — когда токен истекает (или вы получаете `401` с
`code: "not_authenticated"`), просто снова обменяйте свой API-ключ на свежий
токен.

Распространённый подход — кешировать один токен в памяти и повторно обменивать
ключ, когда срок действия токена приближается к концу (или лениво, при первом
`401`).

Один API-ключ можно обменивать столько раз, сколько нужно. Держите ключ в
секрете, а токены — короткоживущими: не храните токены дольше их 2-часового окна.

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

Чтобы попробовать API, вам не обязательно выполнять этот двухшаговый процесс
вручную. Интерактивный **API Explorer** в разделе [API Reference](/api-reference)
выполняет обмен токена за вас:

* Введите **только свой API-ключ `ak_`** в панели авторизации Explorer.
* Когда вы запускаете любой эндпоинт, Explorer вызывает
  `POST /api/v1/auth/token/client` с вашим ключом, читает в ответ `access_token`
  и отправляет его как `Authorization: Bearer <token>` автоматически.
* Вы никогда не вставляете JWT и не авторизуете сам эндпоинт токенов (он публичный).

Explorer работает с `docs.voodoo.center`, который внесён в белый список в
CORS-политике API, поэтому его живые запросы доходят до API и эндпоинта токенов
прямо из вашего браузера.

## Транспорт

Весь доступ осуществляется через `https://api.voodoo.center`, который размещён за
Cloudflare. Всегда используйте HTTPS; запросы по обычному HTTP не поддерживаются.

Теперь, когда вы умеете аутентифицироваться, разместите свой первый заказ.

Сбои аутентификации (`401`) и полный конверт ошибки.