Docs menu

API keys & authentication

Every API key is a pair: a secret key for your servers and a public key you can safely ship in websites and apps.

	Secret key	Public key
Looks like	`smx_sk_live_…`	`smx_pk_live_…`
Where to use it	Servers, back-end jobs, ETL, automation	Browsers, mobile apps, embedded forms, IoT
Sent as	`Authorization: Bearer smx_sk_live_…`	`X-Summarix-Key: smx_pk_live_…`
Can do	Anything its scopes allow (read and write)	Only `POST /v1/ingest`, which appends rows to the key's own dataset
Shown	Once, when created or rolled. Stored as a SHA-256 hash	Any time in the dashboard
Restrictions	Scopes, IP allowlist, expiry	Allowed origins, expiry, strict rate limits

Never put a secret key in client-side code, a mobile app or a public repository. If one leaks, roll it in the dashboard. The public key stays the same, so your embedded snippets keep working.

Creating keys #

Workspace owners and admins manage keys in Dashboard → API keys. You can have up to 20 active keys per workspace. Use one key per integration so you can revoke it on its own and see its last used time.

Scopes #

Give each key only the scopes it needs. A request that needs a scope the key doesn't have returns 403.

Scope	Allows
`reports:read`	List reports and fetch results
`reports:write`	Generate new AI reports
`datasets:read`	List datasets
`datasets:write`	Upload files and push rows
`calls:read`	Call summaries and transcripts
`calls:write`	Upload recordings for summarising

Using the secret key #

curl https://api.summarix.co.za/v1/whoami \
  -H "Authorization: Bearer smx_sk_live_…"

IP allowlist: if you list IP addresses on the key, requests from any other IP get 403. Use this for fixed-IP servers.
Expiry: keys can expire after a set number of days, which is useful for contractors and short-lived integrations.

Using the public key #

Public keys are for collecting data from places where a secret can't be kept, such as a sign-up form, a point-of-sale tablet or a mobile app. They can only append rows (the /v1/ingest endpoint) to a dataset called <key name> (public key), so they can never read anything.

browser

await fetch("https://api.summarix.co.za/v1/ingest", {
  method: "POST",
  headers: { "X-Summarix-Key": "smx_pk_live_…", "Content-Type": "application/json" },
  body: JSON.stringify({ event: "quote_requested", product: "Fibre 100", province: "WC" }),
});

Allowed origins: add your site origins (e.g. https://www.example.co.za). Browser requests from any other origin are rejected. Origin checks stop other websites using your key, but a determined script can fake the header. That's why public keys are write-only and rate-limited (30 requests per minute per visitor IP).

Rotation & revocation #

Roll secret: issues a new secret immediately and the old one stops working. The public key, scopes and restrictions don't change.
Revoke: disables both keys permanently. Data already sent is kept.
All key actions (created, rolled, revoked) are recorded in the workspace audit log.