Authentication
How to authenticate requests to the Spoks Public API.
Every request — apart from the
public embed listings — is
authenticated with an API key, sent in the x-api-key request header.
Sending your API key
Send the key in the x-api-key header on every request:
curl https://api.spoks.com/workspaces \
-H "x-api-key: YOUR_API_KEY"A request missing the header — or with an unrecognized key — is rejected with
403 Forbidden resource. A valid key without the
right permission gets the same 403.
Getting an API key
API keys are issued per workspace. Store the key somewhere safe when it is created.
A key is scoped to the workspace it belongs to — the data you can reach is the data that workspace can see. Endpoints carry no workspace id in the path: the API resolves the workspace (and the region your data lives in) from the key itself.
Permissions
Every key has a set of permissions, one per resource — read-only or
read-write (read-write covers read-only too). Each endpoint's reference page
shows the permission it needs. Call something your key isn't allowed to and
you get the same 403 Forbidden resource as with an
invalid key.
Verifying your key
Check that a key works — and what it can do — with the authorization endpoint. It returns the workspace the key is scoped to, plus its permissions:
curl https://api.spoks.com/authorization \
-H "x-api-key: YOUR_API_KEY"Keep your key safe
Treat the API key like a password. Never embed it in client-side code, mobile apps, or public repositories — anyone with the key can act as your workspace.
- Store the key in a secret manager or environment variable, never in source control.
- Rotate a key immediately if you suspect it has leaked.
- Use a separate key per integration so you can revoke one without breaking the others.