Token format
. matters: both halves are base64url, whose alphabet includes _, so
splitting on anything else truncates some tokens. Send the string exactly as
issued.
Tokens from non-production environments are prefixed sk_test_ instead.
Only the selector is stored. The verifier is hashed, so a lost token cannot
be recovered — ask a workspace administrator to create a replacement and revoke
the old one. Revocation takes effect immediately, not at the end of a cache
window.
Scopes
A scope is<resource>:<access>. read covers list and retrieve; write
covers create, update, and delete.
Ask for the narrowest set that does your job. Calling an endpoint without its
scope returns
403 insufficient_scope, and the message names the scopes you are
missing.
Scopes intersect with what your workspace is allowed to do — they never
grant beyond it. A token with
deals:write still cannot write deals in a
workspace whose deals are mirrored from an external CRM. Call
GET /v1/capabilities to see the effective policy per entity before you
attempt a write.Two limits worth knowing up front
A token reads the whole workspace. Sailer’s per-user record visibility rules apply to people, not tokens — a token has no user behind it. Anything in the workspace is readable with the right scope, regardless of who owns the record. Treat a token as workspace-wide access and scope it accordingly. Write policy still applies. If a workspace mirrors an entity from an external CRM, writes to that entity are rejected for everyone, tokens included. This is deliberate: it stops the API from silently diverging from the system of record.GET /v1/capabilities reports which entities you may write.
Keeping tokens safe
- Server-side only. A token in browser or mobile code is a workspace-wide leak.
- Environment variables or a secret manager, never source control.
- One token per integration, so you can revoke one without breaking the others.
- Tell us immediately if one leaks and we will revoke it.