Get started

Setora API authentication

Every request is authenticated with an API key issued from the Hub. Keys are scoped to a single organisation, so they cannot read or modify data belonging to any other shop on Setora.

Issuing a key

Owners and admins can create API keys from hub.setora.co.uk → Settings → Developer. Each key has a label, a scope (read or read_write), and a creation timestamp. The plaintext key is shown once at creation, so store it somewhere safe (a secrets manager, an env var on your server) and never commit it to source control.

Setora stores only a hash of the key. If a key is lost, revoke it and create a new one.

Sending a request

Pass the key in the Authorization header as a Bearer token. All requests must use HTTPS. Plain HTTP is rejected at the edge.

bashAuthenticated request

curl https://rest.setora.co.uk/v1/locations \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

The organisation context is resolved from the key, so you do not pass an org ID. Endpoints that act on a specific resource take its identifier in the path (a location slug or a booking reference).

Scopes

Scopes are coarse-grained in v1. Webhooks and per-resource scopes are not supported in the current alpha.

Read-only access

`read`

Locations, services, staff, availability, clients, and bookings can be fetched. Mutations are blocked.

Read and mutate

`read_write`

Adds the ability to create clients, create bookings, reschedule, and cancel. Use the narrowest scope your integration needs.

Failure modes

Authentication errors return 401 with a stable error code. See conventions for the full error envelope.

json401 Unauthorized

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "param": "Authorization"
  }
}

missing_api_key: no Authorization header was sent.
invalid_api_key: the key does not match any active record (revoked, deleted, or malformed).
insufficient_scope: the key is valid but the scope does not permit the request. Returned as 403.

Key rotation and revocation

Rotate keys at least every 90 days for active integrations. You can have multiple active keys per org. Rotate by creating a new key, switching your client, then revoking the old key.
Revocation is immediate. Once a key is revoked, every in-flight request using it begins to fail with invalid_api_key.
Each key tracks last_used_at. Use the Hub to spot keys that haven't been used in weeks and clean them up.

Security guidance

Keep keys server-side. Never embed a Setora API key in a mobile app, browser bundle, or anywhere it can be extracted by an end user.
Use read scope wherever you only need to fetch data, for example a display board showing today's bookings.
Treat client phone numbers and booking details as personal data. The shop is the data controller and Setora is its processor. Your own role depends on your agreement with the shop.