# Awrora API

> A JSON REST API for reading and writing your Awrora booking data — experiences, availability, bookings, customers and gift cards.



The Awrora API lets an external system read and write the same booking data your staff see in Awrora: experiences, departures with live seat counts, bookings, customers and gift cards. It can create and cancel bookings, and it can push changes to you as [webhooks](/developers/webhooks) instead of making you poll.

It is a plain JSON REST API over HTTPS. No SDK is required. The API is in **beta**: the shapes are stable and will not break without a new version, but we are still adding to them.

## Base URL

```text
https://your-site.awrora.app/api/v1
```

Use **your own Awrora address** — the same host your staff log in on. There is no separate API domain.

Which organisation you are reading comes from the **API key**, never from the host and never from a parameter. A key issued by one organisation cannot see another's data, and a request for an id that belongs to someone else answers `404`, exactly like an id that does not exist.

## Who can use it

The API is included in the **paid plans** and is managed under <Path>Settings → Apps → For developers</Path>. Administrators and the owner can see that section; only the **owner** can create and revoke keys and manage webhooks. Two independent gates apply:

| Gate                              | Response when closed          | Who opens it                                      |
| --------------------------------- | ----------------------------- | ------------------------------------------------- |
| The organisation has no API yet   | `403` `app_not_enabled`       | The owner, by creating their first key or webhook |
| The plan does not include the API | `403` `plan_upgrade_required` | Requires a plan change                            |

## Quick start

<Steps>
  <Step title="Create a key">
    In Awrora, open <Path>Settings → Apps → For developers</Path> and click **New API key**. Pick the [scopes](/developers/authentication#scopes) you need. The key is shown **once** — copy it now.
  </Step>

  <Step title="Call GET /v1/me">
    `GET /v1/me` needs no scope and is the auth test:

    ```bash
    curl -H "Authorization: Bearer aur_YOUR_KEY" \
      https://your-site.awrora.app/api/v1/me
    ```
  </Step>

  <Step title="Check the answer">
    The response names the organisation the key belongs to and what the key may do — see [Get me](/api-reference/account/get-me). A `401` means the key is wrong; see [Authentication](/developers/authentication).
  </Step>
</Steps>

## Conventions

* **JSON in, JSON out.** Send `Content-Type: application/json` on requests with a body. Every response is JSON except `204 No Content`.
* **Timestamps are ISO 8601 with an offset**, in the organisation's own timezone (`organization.timezone` from `/v1/me`), e.g. `2026-09-11T20:00:00+02:00`. Date-only parameters are `YYYY-MM-DD` in that same timezone.
* **Money is an integer plus a currency**: `{ "amount_minor": 120000, "currency": "SEK" }` is SEK 1,200.00. Never a float, never a formatted string.
* **Ids are UUIDs** — treat them as opaque strings. `booking_number` is the short human-facing number, unique per organisation only; it is not an id.
* **Nulls are real.** A field that can be absent is `null`, not omitted.
* **Unknown fields are ignored** in query strings and bodies. That means a typo in a body field is silent — check the returned resource against what you sent.

<Cards title="Read on">
  <Card title="Authentication" href="/developers/authentication" icon="key">
    API keys, scopes and the 401 codes.
  </Card>

  <Card title="Errors" href="/developers/errors" icon="code">
    The error envelope, every code and what to retry.
  </Card>

  <Card title="Pagination" href="/developers/pagination" icon="terminal">
    Cursor-based list endpoints.
  </Card>

  <Card title="Idempotency" href="/developers/idempotency" icon="zap">
    Safe retries with Idempotency-Key.
  </Card>

  <Card title="Rate limits" href="/developers/rate-limits" icon="settings">
    Per-key and per-organisation limits.
  </Card>

  <Card title="Webhooks" href="/developers/webhooks" icon="news">
    Signed event delivery and retries.
  </Card>

  <Card title="Versioning" href="/developers/versioning" icon="compass">
    What counts as breaking, and the changelog.
  </Card>

  <Card title="API reference" href="/api-reference" icon="book">
    Every endpoint, generated from the OpenAPI document.
  </Card>
</Cards>