Skip to content
Service API

Authentication

The Service API authenticates requests with an API key, sent as a Bearer token in the Authorization header.

GET /v1/reservations HTTP/1.1
Host: api.useservice.app
Authorization: Bearer sk_live_YOUR_SECRET_KEY

With curl:

Terminal window
curl https://api.useservice.app/v1/reservations \
  -H "Authorization: Bearer $SERVICE_API_KEY"

The examples in these docs read the key from a SERVICE_API_KEY environment variable rather than hard-coding it — keep your real key out of shell history, scripts, and source control.

How keys work

Section titled “How keys work”
  • Keys are per-restaurant. A key authenticates as exactly one restaurant and only ever returns that restaurant’s data. The restaurant is determined by the key — you never pass a restaurant id.
  • Keys are secret. A key beginning with sk_live_ grants full read access to a restaurant’s reservation and guest data. Treat it like a password.
  • Keys are server-side only. Never embed a key in a browser, mobile app, public repository, or any client-side code. Use it only from your backend.
  • Keys are shown once. The full secret is displayed a single time, when the key is created. Only a short suffix (the last 4 characters) is stored and shown afterwards, so store the full value securely on creation. If you lose it, create a new key.
  • Multiple keys are supported. A restaurant can hold several keys (for example, one per integration), so you can rotate or revoke one without disrupting the others.

Getting a key

Section titled “Getting a key”

API keys are self-serve from the back office. An owner or co-owner can manage them under Settings → Developers:

  1. Open Settings → Developers and create a new API key.
  2. Copy the secret (sk_live_…) — it is shown once, at creation. Store it somewhere secure before you leave the page.
  3. Send it as a Bearer token, as shown above.

Each key is pinned to an API version at creation and can be revoked at any time from the same screen. A restaurant can hold up to 10 keys — keep one per integration so you can rotate or revoke individually.

There is no separate sandbox or test environment: all keys are live (sk_live_…) and read your real reservation and guest data over the single production base URL. Because the API is read-only, requests never modify data — but treat the data you read as real.

Authentication errors

Section titled “Authentication errors”

A missing, malformed, revoked, or unknown key returns 401 Unauthorized with an error envelope. There are two authentication codes:

  • auth_header_missing — no Authorization: Bearer … header was sent.
  • invalid_token — a key was sent but is invalid, revoked, expired, or unknown.
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_token",
    "message": "The provided API key is invalid, revoked, or expired.",
    "doc_url": "https://docs.useservice.app/api/errors#invalid_token"
  }
}

(param is omitted here — no request parameter is at fault.)