Formato del token
. importa: ambas mitades son base64url, cuyo alfabeto incluye _, así
que partir por cualquier otra cosa trunca algunos tokens. Envía el string
exactamente como se emitió.
Los tokens de entornos que no son producción van prefijados sk_test_ en su
lugar.
Solo se guarda el selector. El verifier se hashea, así que un token
perdido no se puede recuperar — pide a un administrador del workspace que cree
un reemplazo y revoque el anterior. La revocación entra en vigor de inmediato,
no al final de una ventana de caché.
Scopes
Un scope es<resource>:<access>. read cubre list y retrieve; write cubre
create, update y delete.
Pide el conjunto más estrecho que haga tu trabajo. Llamar un endpoint sin su
scope devuelve
403 insufficient_scope, y el mensaje nombra los scopes que te
faltan.
En vivo en /v1 hoy: contacts, organizations, deals y campaigns (incluyendo
audiences), más pipelines, fields y conversations de solo lectura.
pipelines:write y fields:write aún no tienen endpoints — las definiciones
de campos y los pipelines son configuración del workspace, no writes de
partners.
messages:write está definido pero no cableado a nada. No hay send público;
las conversaciones son solo lectura. Los modelos que necesitan enviar lo
hacen a un sandbox a través de Agent Studio.
Notes, activities y tags tienen scopes para poder aterrizar sin un cambio de
formato de token. Aún no tienen endpoints. analytics:read lo usa el
analytics de campañas de MCP, no un resource REST.
Los scopes intersectan con lo que tu workspace puede hacer — nunca
otorgan más allá. Un token con
deals:write igual no puede escribir deals
en un workspace cuyos deals se espejan desde un CRM externo. Llama
GET /v1/capabilities para ver la política efectiva por entidad antes de
intentar un write.Dos límites que conviene saber de antemano
Un token lee todo el workspace. Las reglas de visibilidad por usuario de Sailer aplican a personas, no a tokens — un token no tiene usuario detrás. Cualquier cosa en el workspace es legible con el scope correcto, sin importar quién es dueño del registro. Trata un token como acceso a todo el workspace y asígnalo en consecuencia. La política de escritura sigue aplicando. Si un workspace espeja una entidad desde un CRM externo, los writes a esa entidad se rechazan para todos, tokens incluidos. Es deliberado: evita que la API diverja en silencio del sistema de registro.GET /v1/capabilities reporta qué entidades puedes
escribir.
Cómo cuidar los tokens
- Solo del lado del servidor. Un token en código de browser o mobile es una filtración de todo el workspace.
- Variables de entorno o un secret manager, nunca el control de versiones.
- Un token por integración, para poder revocar uno sin romper las demás.
- Avísanos de inmediato si uno se filtra y lo revocamos.