Autenticação e escopos
Toda requisição leva um token de API no cabeçalho Authorization:
Authorization: Bearer sc_live_…Crie o seu token em Desenvolvedores › Tokens de API (Começando).
Formato do token
Seção intitulada “Formato do token”sc_<ambiente>_ seguido de 32 caracteres aleatórios (base62) e de 6 caracteres de verificação (CRC32), como os tokens do GitHub:
sc_live_vale em produção (dash.halver.com.br);sc_test_, nos ambientes de teste. Um não vale no outro.- O prefixo deixa scanners de segredos reconhecerem um token vazado, e a verificação descarta textos que só se parecem com um token.
- A Halver guarda só um hash do token: ele aparece uma vez, na criação.
Escopos
Seção intitulada “Escopos”Cada token tem uma lista de escopos, e cada operação da referência diz o escopo de que precisa. Escrita inclui a leitura do mesmo recurso: um token com servers:write também lê servidores. servers:delete e servers:console também incluem servers:read.
| Escopo | Permite | Inclui |
|---|---|---|
servers:read |
Listar e ver servidores, operações, catálogo (planos, estoque, sistemas), a disponibilidade do console serial e da VPN da IPMI | |
servers:write |
Contratar servidores (gera cobrança), conferir cupom, ligar, desligar, reiniciar, escolher o próximo boot, mudar hostname, tags, descrição e as referências do revendedor, desfazer um cancelamento | servers:read |
servers:delete |
Cancelar no fim do período pago, apagar o sistema e reinstalar | servers:read |
servers:console |
Abrir, ler, digitar, baixar a gravação e encerrar o console serial; abrir e encerrar a VPN da IPMI | servers:read |
ssh_keys:read |
Listar e ver chaves SSH | |
ssh_keys:write |
Cadastrar, renomear e remover chaves SSH | ssh_keys:read |
networks:read |
Ver a rede da conta e as redes privadas | |
networks:write |
Criar, alterar e apagar redes privadas; colocar e tirar servidores | networks:read |
ips:read |
Ver IPs elásticos | |
ips:write |
Contratar (gera cobrança), mover e liberar IPs elásticos | ips:read |
invoices:read |
Listar e ver faturas e comprovantes | |
payment_methods:read |
Ver os cartões salvos (bandeira, final e validade) | |
support:read |
Ver chamados | |
support:write |
Abrir, responder e resolver chamados | support:read |
GET /me responde a qualquer token, sem escopo.
Sem o escopo, a resposta é 403 com o código api_token.insufficient_scope e o cabeçalho:
WWW-Authenticate: Bearer error="insufficient_scope", scope="servers:write"O token nunca pode mais do que a pessoa
Seção intitulada “O token nunca pode mais do que a pessoa”Um token age em nome de quem o criou:
- Quem tem acesso de consulta à conta (papel
viewer) só cria tokens de leitura. - Se o papel da pessoa diminuir, o token passa a valer só o que o novo papel permite. A resposta diz isso: “o token tem o escopo servers:write, mas o seu acesso a esta conta é só de consulta”.
- Se a pessoa sair da conta ou a conta for desativada, todos os tokens dela param.
- O responsável pela conta vê os tokens de todos os usuários e pode revogá-los.
Cada pessoa tem até 25 tokens ativos.
Rodízio e revogação
Seção intitulada “Rodízio e revogação”- Rodízio: em Desenvolvedores › Tokens de API, Gerar novo segredo cria um token com o mesmo nome, os mesmos escopos e a mesma validade. O antigo para agora ou funciona por mais 1 hora, 24 horas ou 7 dias, à sua escolha, para você trocar sem parar a integração.
- Revogação: um token vazado para de funcionar na hora em que você o revoga, na mesma tela.
- Validade: um token com validade para de funcionar sozinho no fim do prazo.
O painel mostra, para cada token, quando e de qual IP ele foi usado pela última vez. A trilha de auditoria da conta registra a criação, o rodízio e a revogação, toda operação de escrita feita com o token (rota e resultado) e uma amostra das leituras.
Respostas de autenticação
Seção intitulada “Respostas de autenticação”| Situação | Resposta |
|---|---|
| Sem token, token inválido, expirado ou revogado | 401 auth.unauthorized com WWW-Authenticate: Bearer error="invalid_token" |
Token do outro ambiente (sc_test_ em produção) |
401 auth.unauthorized |
| Token emitido por OAuth para o servidor MCP | 401 auth.unauthorized: ele vale só no servidor MCP |
| Falta o escopo | 403 api_token.insufficient_scope |
| A rota não aceita token | 403 api_token.route_not_allowed |
O que um token não faz
Seção intitulada “O que um token não faz”Algumas áreas do portal não aceitam token, só a sessão de uma pessoa no painel, e respondem 403 api_token.route_not_allowed:
- criar, girar e revogar tokens;
- cadastrar cartão e pagar faturas;
- firewalls;
- aprovar ações pedidas por uma IA no servidor MCP.
Boas práticas
Seção intitulada “Boas práticas”- Um token por integração, com o mínimo de escopos e com validade.
- Use o token só no servidor. A API não libera o cabeçalho
Authorizationpara páginas de outros sites (CORS): um token nunca deve ir para o navegador. - Guarde o token num cofre de segredos ou numa variável de ambiente, nunca no código nem no repositório.
- Faça o rodízio periodicamente e revogue os tokens que não usa mais.