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.
To create, expire, or revoke a token in the Sailer app, see
Create and manage API tokens.
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.
Live on /v1 today: contacts, organizations and deals (including deletes,
the deletion feed and bulk upserts), notes, activities, tags, lost reasons,
users, pipelines, fields, campaigns and audiences, conversations (reading them,
and handing them between the AI and your team), channels, templates and success
events. Listing deleted records needs the read scope of the resource you list.
pipelines:write and fields:write have no endpoints yet — field definitions
and pipelines are workspace configuration, not partner writes.
messages:write is defined but wired to nothing. There is no public send:
conversations:write changes who handles a conversation, never what is said in
it. Models that need to send do so into a sandbox through
Agent Studio.
analytics:read is used by MCP campaign analytics, not by a REST resource.
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.