As formas de acesso da API, o escopo de cada uma, o token pessoal da API v1 e o login pelo terminal, como rodar e revogar chaves e tokens e como guardar segredos.
Nesta página
As formas de acesso
Cada entrada de integração do Steel tem uma forma de acesso própria. Nenhuma
delas usa usuário e senha.
O workspace, os módulos e o escopo que o usuário concedeu ao cliente de IA
Sessão de usuário
Cookie better-auth.session_token
/api/workspaces/<id>/... e o resto da API
O que o usuário pode fazer no aplicativo
Toda chave e todo token valem para um único workspace e um único ambiente: o que
foi criado em homologação não funciona em produção.
Qual usar:
Scripts, CI, integrações internas e o terminal: token pessoal, na API v1.
Um site ou sistema que só envia leads: chave de API do CRM, que não lê
nada.
Um sistema de monitoramento, um formulário ou um workflow: a URL com
token daquela entrada.
Um cliente de IA (Claude, ChatGPT, Cursor): o OAuth do
servidor MCP.
Token pessoal
O token pessoal (stl_pat_ seguido de 43 caracteres) é a forma de acesso da
API pública v1, do Steel CLI e do
SDK. Ele age em seu nome: cada chamada roda com o seu papel e o
seu perfil de acesso no workspace, como no aplicativo, e cada alteração fica
registrada na auditoria com origem api.
Cada token tem:
um workspace;
módulos (ServiceDesk, CRM, Comunicação), entre os habilitados no
workspace;
um nível de acesso:Somente ler (api:read) ou Ler e alterar
(api:read e api:write);
uma validade: 7, 30, 90 ou 180 dias, ou 1 ano. O padrão é 90 dias.
Cada pessoa pode ter até 50 tokens ativos; o próximo responde
422 API_TOKEN_LIMIT_REACHED. O que cada escopo e cada módulo libera, e os
erros 403 que eles geram, estão em API pública v1.
Crie um token na tela
Para o CI, um servidor ou qualquer lugar sem navegador:
No Steel, abra Configurações › Segurança › Tokens de API e clique em Criar
token.
Preencha o Nome (por exemplo, "Deploy no GitHub Actions"), o
Workspace, os Módulos, o Nível de acesso e a Validade.
Clique em Criar token. A janela Token criado mostra o valor uma
única vez: copie e clique em Concluir. O Steel guarda só um hash.
A lista mostra, de cada token, o nome, o nível de acesso, o começo do valor
(stl_pat_ e mais 8 caracteres), o workspace e os módulos, a criação, a
validade e o último uso.
Ou entre pelo terminal (fluxo de dispositivo)
No seu computador, o steel login cria o token sem você copiar nada:
O CLI pede um código ao Steel (POST /api/v1/auth/device) e mostra um
código de 8 caracteres, como BCDF-GH23.
O navegador abre /device. Você confere o código, escolhe o workspace, os
módulos, o nível de acesso e a validade, e clica em Permitir acesso.
Enquanto isso, o CLI consulta POST /api/v1/auth/device/token a cada 5
segundos. Aprovado, recebe o token, chamado Steel CLI — <máquina>, e o
guarda no chaveiro do sistema.
O código vale 10 minutos. Quem clica em Recusar encerra o login. O passo a
passo, com as mensagens do terminal, está em
Steel CLI; para fazer o mesmo no seu próprio
programa, use o waitForDeviceToken do SDK.
Revogação e validade
Você: em Configurações › Segurança › Tokens de API, clique em Revogar
no token. O steel logout revoga o token do CLI
(DELETE /api/v1/auth/token).
Os administradores: o dono e os administradores do workspace veem os
tokens de todos os membros em Ajustes › Apps conectados › Tokens de API e
podem revogar qualquer um.
Um token também deixa de valer quando vence ou quando você sai do workspace.
O efeito é imediato: a próxima chamada responde 401 UNAUTHORIZED. Um token
revogado não volta; crie outro. Para trocar um token sem parar um job, crie o
novo, troque o segredo do CI e só então revogue o antigo.
Chave de API do CRM
A chave é a forma de acesso de quem envia leads de outro sistema. Ela tem um só
escopo, criar leads, e não lê nada do CRM.
Quem cria: o dono ou um administrador do workspace, com o módulo CRM
habilitado, em CRM › Chaves de API, no menu lateral do CRM.
O passo a passo está em Começando.
Formato:crm_live_ seguido de 32 caracteres. O valor completo aparece
uma única vez, na criação; depois a tela mostra só o começo da chave, para você
reconhecê-la.
Como enviar: no header Authorization, com o prefixo Bearer .
Leads criados pela chave ficam registrados como criados por quem gerou a
chave, com origem integration e canal API quando o corpo não informa
source e channel.
Uma chave não expira. Para trocá-la sem parar a integração:
Crie uma chave nova com outro nome (por exemplo, "ERP 2026-10").
Troque o segredo no seu sistema e confirme que as chamadas seguem com 201
ou 200.
Revogue a chave antiga.
Faça isso sempre que alguém que conhecia a chave sair da equipe, e pelo menos
uma vez por ano.
Revogação
Na tela Chaves de API, revogue a chave. O efeito é imediato: a próxima
chamada com ela responde 401 CRM_INTEGRATION_KEY_INVALID. Uma chave revogada
não volta a funcionar; crie outra.
Tokens na URL
Formulários, workflows e origens de monitoramento usam um token dentro da
URL. Quem tem a URL consegue usar a entrada, então trate a URL inteira como uma
senha.
Formulário do CRM: o token é o da página pública /f/<token>, criado
junto com o formulário. Ele só aceita envios enquanto o formulário estiver
publicado.
Workflow do CRM: o token aparece no gatilho Webhook do editor de
workflows. A URL só responde enquanto o workflow estiver ativo, e roda a
versão ativa. Para invalidar uma URL, troque o token no gatilho e ative o
workflow de novo.
Origem de monitoramento do ServiceDesk: criada em ServiceDesk ›
Configurações › Monitoramento por quem administra o ServiceDesk. A URL com o
token aparece uma única vez. Gerar token cria outro e o anterior para
de funcionar na hora; desativar a origem faz a URL responder como token
inválido.
Assinaturas de webhook
O GitHub e o GitLab chamam o Steel, e não o contrário. O acesso é provado pelo
segredo que você cadastrou no Steel e no repositório:
GitHub: o Steel calcula o HMAC-SHA256 do corpo bruto com o segredo do
webhook e compara, em tempo constante, com X-Hub-Signature-256.
GitLab: o GitLab não assina o corpo; o Steel compara o
X-Gitlab-Token com o segredo, também em tempo constante.
As rotas em /api/workspaces/<id>/... (chamados, registros do CRM, conversas,
configurações) são as que o aplicativo do Steel usa. Elas exigem o cookie de
sessão que o login define (better-auth.session_token; em HTTPS,
__Secure-better-auth.session_token) e respondem 401 UNAUTHORIZED sem ele.
Cada chamada vale pelo usuário da sessão: papel no workspace, módulos habilitados
e perfis de acesso.
Essas rotas não aceitam token pessoal nem chave de API, e podem mudar a cada
versão. Para uma integração, use a API pública v1 ou as entradas
acima; se o seu caso precisar de uma rota que a v1 ainda não tem, fale com o
suporte antes de automatizar um login.
Guarde os segredos com cuidado
Guarde chaves e URLs com token num cofre de segredos ou em variáveis de
ambiente do servidor. Nunca no repositório, no front-end, num aplicativo móvel
ou numa planilha compartilhada.
Use uma chave por sistema. Assim dá para revogar uma sem derrubar as outras.
Não registre o header Authorization nem URLs com token nos logs do seu
sistema.
Vazou? Revogue a chave ou gere outro token antes de investigar.
