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.
Para criar, definir a expiração ou revogar um token no app da Sailer, veja
Criar e gerenciar tokens de API.
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: contatos, organizações e negócios (incluindo exclusões, o
feed de exclusões e upserts em massa), notas, atividades, tags, motivos de
perda, usuários, funis, campos, campanhas e audiências, conversas (lê-las e
passá-las entre a IA e sua equipe), canais, templates e eventos de sucesso.
Listar registros excluídos exige o scope de leitura do recurso listado.
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:
conversations:write muda quem atende uma conversa, nunca o que é dito nela.
Modelos que precisam enviar fazem isso num sandbox pelo
Agent Studio.
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.