---
title: "Автентифікація · API Reference: документація AOA API"
description: "API-ключі AOA: як отримати, як передавати в запиті, які scopes існують і що вони відкривають."
canonical: "https://aoa.com.ua/docs/api-reference/authentication"
---

# Автентифікація

API-ключі AOA: як отримати, як передавати в запиті, які scopes існують і що вони відкривають.

## Free tier: без ключа

Пошук закладів і подій, деталі, вільний час і залишки квитків безкоштовні й працюють без реєстрації та API-ключа: 60 запитів на хвилину з IP. Ключ потрібен лише для дій, що змінюють стан: резервування, оплата, вебхуки.

Ключ передається у заголовку `Authorization` зі схемою `Bearer`. Усі ключі починаються з `aoa_live_`.

```bash
curl https://aoa.com.ua/api/v1/events \
  -H "Authorization: Bearer aoa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## Як отримати ключ

Самостійної видачі ключів поки немає. Напишіть нам, розкажіть, що плануєте будувати, — ми створимо ключ і надішлемо його вам. Одразу оберемо потрібні дозволи: якщо інтеграція лише показує афішу, доступ до оплати їй не потрібен.

Поки ключа немає, інтеграцію повністю збирають у [пісочниці](https://aoa.com.ua/docs/api-reference/sandbox): там працюють ті самі запити, а тестовий ключ `aoa_test_…` ви придумуєте самі, без звернення до нас.

Ключ показується один раз

Ми зберігаємо лише хеш, тож відновити ключ неможливо — якщо він загубився, ми відкликаємо старий і видаємо новий. Зберігайте його як пароль: у змінних середовища, ніколи в репозиторії чи в коді клієнта.

## Дозволи

Кожен ключ має набір дозволів. Ендпоінт перевіряє свій дозвіл окремо, тож ключ для показу афіші не зможе провести оплату.

| Дозвіл | Що відкриває |
| --- | --- |
| `events:read` | Читання подій. Позначає намір інтеграції — самі ці ендпоінти відкриті й без ключа. |
| `reservations:write` | **POST** `/reservations` — тимчасове утримання квитків; **POST** `/table-reservations` — підтверджене бронювання столика |
| `checkout:write` | **POST** `/checkout` і **GET** `/orders/{paymentId}` |

Для повного циклу продажу потрібні `reservations:write` та `checkout:write`.

## Ключ належить організації

Кожен партнерський ключ привʼязаний до однієї організації. Це визначає, чиї дані ви отримуєте: вебхуки надходять лише про події та продажі вашої організації, а замовлення, створені вашим ключем, бачите тільки ви.

Дані інших організаторів через ваш ключ недоступні — ані їхні продажі, ані суми, ані скасування. Якщо працюєте з кількома організаціями, візьміть окремий ключ на кожну.

Читання подій — публічне

Ендпоінти афіші показують усі опубліковані події платформи, а не лише вашої організації: це та сама інформація, що на сайті. Привʼязка до організації обмежує саме приватні дані — вебхуки й замовлення.

## Коли ключ потрібен

Ендпоінти подій працюють без ключа. Але ключ у запиті піднімає ліміт з 60 до 600 запитів на хвилину, тому надсилати його варто завжди — див. [Ліміти запитів](https://aoa.com.ua/docs/api-reference/rate-limits).

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

## Помилки доступу

Невірний, відкликаний або відсутній там, де він потрібен, ключ дає `401`:

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}
```

Якщо ключ дійсний, але не має потрібного дозволу — `403` із точною назвою того, чого бракує:

```json
{
  "error": {
    "code": "forbidden",
    "message": "Missing required scope: checkout:write"
  }
}
```

Різниця істотна: `401` означає проблему з самим ключем і повторювати запит немає сенсу, `403` — що ключ живий, але йому треба розширити дозволи. Напишіть нам, і ми це зробимо.

## Безпека

- Тримайте виклики на сервері. Ключ у браузерному коді або в мобільному застосунку вважайте скомпрометованим.
- Помітили витік — напишіть нам, ми відкличемо ключ негайно. Відкликаний ключ перестає діяти одразу.
- Для різних інтеграцій беріть різні ключі: так відкликання одного не зупинить решту.