Fundamentos
Autenticação
Uma chave de API por integração, enviada como Bearer token. Sem OAuth, sem troca de token.
Enviando a chave
Toda requisição leva a chave no header Authorization, com a palavra Bearer e um espaço:
Authorization: Bearer oneos_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
A chave começa com oneos_sk_. A Oneos guarda só o hash — não há como recuperá-la depois de criada.
Quem perdeu a chave gera outra.
Criando a chave
Em Minha empresa › Integração › Nova chave. Uma empresa pode ter várias chaves ativas — uma por sistema, por exemplo — e cada uma tem nome, usuário responsável e escopos próprios.
Usuário responsável
As operações feitas com a chave saem em nome do usuário responsável. A cada requisição a Oneos confere
se ele continua na empresa e com a permissão que o escopo exige. Se a pessoa sair da empresa ou perder a permissão, a
chave para de funcionar com 403 — crie uma nova chave com outro responsável e revogue a antiga (a rotação
mantém o mesmo responsável). Na criação, a plataforma só deixa escolher quem tem a permissão dos escopos marcados.
Escopos
Pelo menos um escopo é obrigatório. Cada escopo exige uma permissão do responsável:
| Escopo | Na plataforma | Permissão do responsável | Usado por |
|---|---|---|---|
preauth:write |
Criar e cancelar pré-autorizações | Solicitar e pré-autorizar antecipações | Criar e cancelar pré-autorização |
preauth:read |
Consultar pré-autorizações | Ver antecipações e boletos | Consultar pré-autorizações |
notes:read |
Consultar notas fiscais | Ver notas fiscais | Nenhum endpoint. Não é mais oferecido para chaves novas; chaves antigas que o têm continuam funcionando. |
Para criar e cancelar, preauth:write. Para consultar, acrescente preauth:read — o responsável
precisa das duas permissões.
Validade, rotação e revogação
-
Validade: escolhida na criação, entre 30, 90, 180, 365 dias (padrão
365). A data aparece na lista de chaves. Depois disso a chave responde
401 API_KEY_EXPIRED. Anote a data e troque antes. - Rotacionar revoga a chave atual e gera uma nova com o mesmo nome, responsável e escopos — e a mesma data de expiração. A antiga para na hora.
- Revogar desliga a chave imediatamente e para sempre.
Erros de autenticação
| Status | Código | Quando acontece |
|---|---|---|
| 401 | API_KEY_INVALID |
Header ausente, sem Bearer , sem o prefixo ou chave desconhecida.
|
| 401 | API_KEY_REVOKED |
A chave foi revogada ou rotacionada. |
| 401 | API_KEY_EXPIRED |
A chave passou da validade. |
| 403 | INTEGRATION_SCOPE_FORBIDDEN |
A chave não tem o escopo exigido pelo endpoint. |
| 403 | INTEGRATION_RESPONSIBLE_FORBIDDEN |
O usuário responsável não tem a permissão que o escopo exige. |
| 403 | RBAC_FORBIDDEN |
O usuário responsável não faz mais parte da empresa. |