Formato do token
. importa: as duas metades são base64url, cujo alfabeto inclui _, então
partir por qualquer outra coisa trunca alguns tokens. Envie o string
exatamente como foi emitido.
Tokens de ambientes que não são produção vêm prefixados sk_test_ no lugar.
Só o selector é armazenado. O verifier é hasheado, então um token perdido
não pode ser recuperado — peça a um administrador do workspace para criar um
substituto e revogar o antigo. A revogação entra em vigor imediatamente, não
no fim de uma janela de cache.
Scopes
Um scope é<resource>:<access>. read cobre list e retrieve; write cobre
create, update e delete.
Peça o conjunto mais estreito que faça o seu trabalho. Chamar um endpoint sem
o seu scope devolve
403 insufficient_scope, e a mensagem nomeia os scopes
que estão faltando.
No ar em /v1 hoje: contacts, organizations, deals e campaigns (incluindo
audiences), mais pipelines, fields e conversations somente leitura.
pipelines:write e fields:write ainda não têm endpoints — definições de
campos e pipelines são configuração do workspace, não writes de partners.
messages:write está definido mas não ligado a nada. Não há send público;
conversas são somente leitura. Modelos que precisam enviar fazem isso num
sandbox pelo Agent Studio.
Notes, activities e tags têm scopes para poder aterrissar sem mudança de
formato de token. Ainda não têm endpoints. analytics:read é usado pelo
analytics de campanhas do MCP, não por um resource REST.
Scopes intersectam com o que o seu workspace pode fazer — nunca
concedem além disso. Um token com
deals:write ainda não consegue escrever
deals num workspace cujos deals são espelhados de um CRM externo. Chame
GET /v1/capabilities para ver a política efetiva por entidade antes de
tentar um write.Dois limites que vale saber de antemão
Um token lê o workspace inteiro. As regras de visibilidade por usuário da Sailer valem para pessoas, não para tokens — um token não tem usuário atrás. Qualquer coisa no workspace é legível com o scope certo, independentemente de quem é dono do registro. Trate um token como acesso a todo o workspace e dê scope de acordo. A política de escrita continua valendo. Se um workspace espelha uma entidade de um CRM externo, writes nessa entidade são rejeitados para todo mundo, tokens incluídos. É deliberado: impede a API de divergir em silêncio do sistema de registro.GET /v1/capabilities reporta quais entidades você pode
escrever.
Como guardar tokens
- Só no servidor. Um token em código de browser ou mobile é um vazamento de todo o workspace.
- Variáveis de ambiente ou um secret manager, nunca o controle de versão.
- Um token por integração, para você revogar um sem quebrar os outros.
- Avise a gente imediatamente se um vazar e vamos revogá-lo.