Skip to main content
Tokens de API são criados no app da Sailer. Qualquer pessoa com a permissão de Configuration no workspace pode criá-los; administradores da organização têm essa permissão por padrão. Se você não tem, peça a um deles para seguir esta página por você.

​
Encontre a aba API

1

Abra Perfil da Empresa

Na barra lateral, em Configurações, clique em Perfil da Empresa.
O item Perfil da Empresa em Configurações, na barra lateral da Sailer
2

Escolha o workspace e abra API

Clique na empresa cujos dados a integração vai usar e abra a aba API.
A aba API, com dois tokens ativos acima da chave de API legada
A aba lista todos os tokens do workspace: o nome, os últimos caracteres do token, quantos scopes ele tem, o status, quando foi criado, quando foi usado pela última vez e quando expira. Clique no número de scopes para ver a lista completa.

​
Crie um token

1

Dê um nome, uma expiração e os scopes

Clique em Criar token.
  • Nome: para que serve o token, por exemplo a integração a que ele pertence. Até 120 caracteres. Só as pessoas do workspace veem.
  • Expiração: Nunca expira, 30 dias, 90 dias ou 1 ano. Veja Expiração.
  • Escopos: pelo menos um. Veja Escolher scopes.
O diálogo Criar token de API com um nome, expiração de 90 dias e três scopes selecionados
2

Copie o token

Clique em Criar token. O token é mostrado uma única vez. Clique em Copiar e guarde-o no gerenciador de segredos ou nas variáveis de ambiente da sua integração.
A única exibição de um token novo, com um botão Copiar e um aviso de que ele não será mostrado de novo
A Sailer guarda só um hash do token, então ninguém consegue mostrá-lo de novo. Esta tela só fecha quando você clica em Concluir. Se perder o token, revogue-o e crie um novo.
3

Confira que funciona

A resposta informa o workspace e lista os scopes do token. Veja o Quickstart para a sua primeira requisição de verdade.

​
Escolher scopes

O seletor agrupa os scopes por área, com uma coluna por nível de acesso. Ler cobre listar e buscar registros. Escrever cobre criar, atualizar e excluir. Toda leitura seleciona todos os scopes de leitura, Selecionar todos seleciona tudo e Limpar remove todos os scopes. Escolha o menor conjunto de que a integração precisa. Um token lê o workspace inteiro dentro dos seus scopes, não importa quem seja dono dos registros. Uma chamada sem o scope certo devolve 403 insufficient_scope, e a mensagem nomeia os scopes que faltam.
Nem todo scope do seletor faz algo em um token de API hoje:
  • Os scopes de Agent Studio só funcionam em apps OAuth. Para o Agent Studio, conecte-se por MCP.
  • Mensagens · Escrever (messages:write) não é usado por nenhum endpoint. A API pública não envia mensagens.
Autenticação mostra quais scopes têm endpoints em /v1.
Não dá para mudar os scopes de um token depois de criado. Para mudá-los, crie um token novo com os scopes que você quer, passe a integração para ele e revogue o antigo.

​
Expiração

Quando um token expira, a API responde 401 e o status dele na lista muda para Expirado. Não dá para estender um token. Crie um novo antes de o antigo expirar e depois revogue o antigo. Use uma expiração para tudo que for temporário: um teste, uma importação pontual ou o acesso de um prestador de serviço.

​
Revogue um token

Revogue um token quando uma integração for desativada, quando a pessoa que a configurou sair ou sempre que achar que ele pode ter vazado.
1

Clique em revogar

Na linha do token, clique no ícone de revogar no fim da linha e confirme.
A confirmação Revogar token de API
2

Ele para de funcionar na hora

A próxima requisição com esse token recebe 401. Revogar não pode ser desfeito.
Tokens revogados ficam ocultos na lista. Ative Mostrar revogados para vê-los, por exemplo para conferir quando algo foi desligado.
A lista de tokens com Mostrar revogados ativado: um token revogado e dois ativos

​
Status

Último uso é atualizado no máximo a cada poucos minutos, então um token que você acabou de usar ainda pode mostrar um horário anterior.

​
A chave de API legada

Abaixo da lista de tokens, Chave de API legada mostra a única X-API-KEY do workspace. Webhooks e integrações antigas usam essa chave; a API /v1 não. Use tokens de API para qualquer coisa nova. Gerar nova substitui essa chave na hora. Tudo que usa a chave antiga para de funcionar até ser atualizado, então localize essas integrações antes.

​
Boas práticas

  • Um token por integração, para que revogar um nunca quebre os outros.
  • Mantenha os tokens no servidor. Um token em código de navegador ou mobile expõe o workspace inteiro.
  • Guarde os tokens em variáveis de ambiente ou em um gerenciador de segredos, nunca no controle de versão.
  • Se um token vazar, revogue-o primeiro e investigue depois.