Authentication

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.

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 are not yet supported but are coming soon, and per-resource scopes will land alongside them.

Failure modes

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

{
  "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 production 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.