> 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`) і повний конверт помилки.