API reference
AOA API keys: what works without a key, how to get one and send it in the Authorization header, and which scopes exist and what they unlock.
Searching venues and events, details, free time slots and tickets left are free and work without sign-up or an API key: 60 requests per minute per IP. You only need a key for actions that change state: reservations, payments, webhooks.
The key goes in the Authorization header with the Bearer scheme. All keys start with aoa_live_.
curl https://aoa.com.ua/api/v1/events \
-H "Authorization: Bearer aoa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"There’s no self-service key issuing yet. Write to us and tell us what you plan to build, and we’ll create a key and send it to you. We’ll pick the scopes you need right away: if an integration only shows a listing of events, it doesn’t need access to payments.
Until you have a key, you can build the whole integration in the sandbox: the same requests work there, and you make up the test key aoa_test_… yourself, without contacting us.
The key is shown once
We only store a hash, so a key can’t be recovered: if you lose it, we revoke the old one and issue a new one. Store it like a password, in environment variables, never in a repository or in client code.Every key has a set of scopes. Each endpoint checks its own scope, so a key made for showing events can’t take a payment.
| Scope | What it unlocks |
|---|---|
events:read | Reading events. It marks the integration’s intent: these endpoints are open without a key anyway. |
reservations:write | POST/reservations, a temporary ticket hold; POST/table-reservations, a confirmed table booking |
checkout:write | POST/checkout and GET/orders/{paymentId} |
The full sales cycle needs reservations:write and checkout:write.
Every partner key is tied to one organization. That decides whose data you get: webhooks only arrive about your organization’s events and sales, and only you can see orders created with your key.
Other organizers’ data isn’t available through your key: not their sales, amounts or cancellations. If you work with several organizations, get a separate key for each.
Reading events is public
The event listing endpoints show every published event on the platform, not just your organization’s: it’s the same information as on the website. Tying a key to an organization restricts private data only: webhooks and orders.The event endpoints work without a key. But a key in the request raises the limit from 60 to 600 requests per minute, so it’s worth always sending it. See Rate limits.
Reservation, payment and order status requests don’t go through without a key.
A wrong or revoked key, or a missing one where it’s required, returns 401:
{
"error": {
"code": "unauthorized",
"message": "Invalid API key"
}
}If the key is valid but lacks the required scope, you get 403 with the exact name of what’s missing:
{
"error": {
"code": "forbidden",
"message": "Missing required scope: checkout:write"
}
}The difference matters: 401 means a problem with the key itself and retrying makes no sense; 403 means the key is alive but its scopes need extending. Write to us and we’ll do it.