Authentication

Spotzee uses bearer-token authentication. Pass your API key in the Authorization header on every request:

Authorization: Bearer YOUR_API_KEY

Key types

Spotzee issues three API key types, each with a different prefix and scope.

Prefix	Type	Scope	Where it’s used
`sk_`	Secret	One project	Server-to-server integrations. Full read + write within the issued project.
`pk_`	Publishable	One project, allowlisted endpoints only	Browser, mobile, or any untrusted client. Safe to embed because each endpoint must explicitly allow `pk_`.
`ok_`	Organisation	One organisation	Cross-project administration: create, list, and update projects under your organisation, and manage team API keys.

Treat sk_ and ok_ keys as secrets. Never commit them to source control or embed in clients you do not control. Rotate immediately if you suspect a leak.

Choosing a key

Server backend
Browser or mobile app
Cross-project automation

Use a sk_ project key. It can call every endpoint in the project surface and is the primary integration path for sync, automation, and admin scripts.

Use a pk_ publishable key. It works only for endpoints explicitly allowlisted for browser use:

POST /events: capture behaviour from your front-end
GET /users/me: read the current user’s preferences (requires a user session token)
PATCH /subscriptions/me: let the user update their own opt-ins (requires a user session token)

Any other endpoint returns 401 authentication_required when called with a pk_ key.

Use an ok_ organisation key. These authenticate against the organisation surface (https://apix.spotzee.com/api/admin) and let you create projects, mint new sk_ and pk_ keys, and read organisation-level metadata.

Surfaces

Each key type maps to a base URL.

Key type	Base URL
`sk_` or `pk_`	`https://apix.spotzee.com/api/client`
`ok_`	`https://apix.spotzee.com/api/admin`

Sending a key to the wrong surface returns 401 authentication_required.

Rotate a key

Mint the replacement

Generate a new key in Settings → API keys.

Roll the new key out

Update your integration to use the new key. Both keys are valid during the cutover window.

Revoke the old key

Confirm traffic on the new key, then revoke the old one. Revoked keys return 401 authentication_required immediately.

Errors

HTTP	`code`	When
`401`	`authentication_required`	Missing, malformed, or revoked key
`403`	`permission_denied`	Key lacks the role needed for this resource

Next steps

Versioning

Pin a date-based release.

Rate limits

Per-key budgets and headers.

Idempotency

Make retries safe.

Errors

Status codes and the code catalogue.

Get started

Build

Configure

Integrate

Tools

SDKs

API conventions

Recipes

Releases

Key types

Choosing a key

Surfaces

Rotate a key

Errors

Next steps

Versioning

Rate limits

Idempotency

Errors

​Key types

​Choosing a key

​Surfaces

​Rotate a key

​Errors

​Next steps

Versioning

Rate limits

Idempotency

Errors

Key types

Choosing a key

Surfaces

Rotate a key

Errors

Next steps