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, provision 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”

The API is in beta. Self-serve key management from the back office is on the roadmap but not available yet — for now, keys are provisioned on request: contact the Service team and we generate one for your restaurant. Each key is pinned to an API version at creation.

There is no separate sandbox or test environment in this release: 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.)