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é.
Para crear, hacer caducar o revocar un token en la app de Sailer, ver
Crear y administrar tokens de API.
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: contactos, organizaciones y negocios (incluyendo
eliminaciones, el feed de eliminaciones y upserts masivos), notas, actividades,
etiquetas, motivos de pérdida, usuarios, pipelines, campos, campañas y
audiencias, conversaciones (leerlas y pasarlas entre la IA y tu equipo),
canales, plantillas y eventos de éxito. Listar registros eliminados requiere el
scope de lectura del recurso que listas. 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:
conversations:write cambia quién atiende una conversación, nunca lo que se
dice en ella. Los modelos que necesitan enviar lo hacen a un sandbox a través de
Agent Studio.
analytics:read lo usa el analytics de campañas del 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.