Skip to main content
All requests to the Partner API must be authenticated with a secret API key issued by the Saoma team.

​
API keys

An API key is a long-lived secret that:
  • Identifies your organisation (the partner).
  • Can be scoped to a single venue, or left platform-wide.
  • Carries a set of scopes that gate which endpoints it can call.
  • Can be revoked or regenerated at any time.
Keys are stored securely on Saoma’s side: the secret is held in an encrypted vault, and only its public prefix is kept in clear for lookup. Saoma itself cannot read the value back — the cleartext is only returned to you, and only through the reveal / regenerate actions described below.
Treat API keys like passwords. Never expose them in client-side code (browsers, mobile apps). All calls to the Partner API must originate from your server.

​
Generating your key from the admin dashboard

Each organisation has one active API key, managed self-service from the Saoma admin dashboard.
1

Open the API key page

Sign in to the admin dashboard, open the user menu in the top-right corner and click Clé API (visible only to users with the admin role).
2

Generate a key (first time only)

If no key has been issued for your organisation yet, the page shows a Generate a key button. Click it to create one. The full cleartext key is displayed once in a dialog — copy it immediately.
3

Reveal an existing key

Once a key exists, the page shows its public prefix masked with dots (e.g. sk_live_ab12cd34_••••••••••••••••••••••••). Click the eye icon to reveal the full value, or Copy to copy it to your clipboard. You can do this as many times as needed.
4

Regenerate when needed

Click Regenerate to revoke the current key and issue a new one in a single step. A confirmation dialog warns you that the previous key stops working immediately. See Rotation and revocation for the recommended rollout.
Need a different scope or a venue-restricted key for a specific integration? Contact your Saoma account manager — those keys are still provisioned manually for now.

​
Using your key

Send the key on every request, using either of these headers: 
Authorization: Bearer sk_live_ab12cd34_0f9e8d7c6b5a4938271605f4e3d2c1b0a9f8e7d6

X-Api-Key: sk_live_ab12cd34_0f9e8d7c6b5a4938271605f4e3d2c1b0a9f8e7d6
If both are present, Authorization: Bearer takes precedence.

​
Example

curl https://api.saoma.io/v1/venues \
  -H "Authorization: Bearer $SAOMA_API_KEY"

​
Key format

API keys follow the pattern sk_live_{id}_{secret} where:
  • sk stands for secret key, live for the production environment.
  • id is a short hex identifier (used for lookup and display).
  • secret is a long hex random string — the part you must keep confidential.

​
Rotation and revocation

Rotation is self-service from the Clé API page. Because Regenerate revokes the active key the moment the new one is issued, plan a brief switchover:
  1. Open the Clé API page and click Regenerate.
  2. Copy the new key from the confirmation dialog.
  3. Deploy it to your servers (environment variable, secret manager, …).
  4. Confirm traffic is flowing on the new key — the old one is already rejected.
If you suspect a key has leaked, regenerate immediately; the previous secret becomes unusable at once. A revoked key is rejected with 401 { "error": "Invalid or revoked API key" }.

​
Scopes

Each API key is tagged with one or more scopes. Calls to an endpoint whose scope your key lacks return 403 with { "error": "Insufficient scope", "missing": ["…"] }.
ScopeStatusGrants
venues:readAvailableGET /v1/venues, GET /v1/venues/{venue_id}
treatments:readAvailableGET /v1/venues/{venue_id}/treatments
customers:readAvailableGET /v1/venues/{venue_id}/customers
bookings:readAvailableGET /v1/venues/{venue_id}/customers/{customer_id}/bookings
availability:readComing soonReal-time availability endpoint (not yet released)
bookings:writeComing soonCreate / cancel bookings (not yet released)