Autenticação
Toda chamada à API (exceto as rotas públicas do canal de denúncias e as de login) leva uma credencial no cabeçalho Authorization:
Authorization: Bearer <credencial>
A API reconhece o tipo de credencial pelo formato e aplica regras diferentes para cada um. Escolher o tipo certo é a primeira decisão de qualquer integração.
| Credencial | Formato | Quem usa | Quando escolher |
|---|---|---|---|
| Chave de API | sgk_live_<prefixo>_<segredo> | Sistemas da empresa (servidor para servidor) | Integrações permanentes: ERP, BI, RH, automações |
| Token de acesso de pessoa | JWT de curta duração | O backoffice, em nome de quem fez login | Aplicações em que uma pessoa entra com e-mail e senha |
| Token MCP | JWT emitido via OAuth | Assistentes de IA compatíveis com MCP | Quando uma IA deve agir em nome de uma pessoa (veja MCP) |
Se não há uma pessoa digitando senha e código de segundo fator naquele momento, use uma chave de API.
Chaves de API
Formato
sgk_live_1a2b3c4d_k3Jq...restante-do-segredo
└┬┘ └┬─┘ └──┬───┘ └──────────┬──────────┘
│ │ │ └ segredo (mostrado uma única vez)
│ │ └ prefixo de 8 caracteres (seguro para exibir e registrar)
│ └ ambiente: live (produção) ou test (ambientes de teste)
└ identifica uma chave do NearOne Trust
- Chaves
sgk_live_funcionam em produção. Chavessgk_test_pertencem a ambientes de teste e são recusadas em produção com401. - A API guarda apenas um resumo criptográfico do segredo. Nem a equipe do NearOne Trust consegue recuperá-lo: se você perder o segredo, revogue a chave e emita outra.
- O Prefixo (
sgk_live_1a2b3c4d) aparece nas telas e na listagemGET /api/v1/api-keys. Use-o para identificar qual chave um sistema está usando sem expor o segredo.
Chaves de integração e chaves pessoais
| Chave de integração | Chave pessoal | |
|---|---|---|
| Onde criar | Integração › Chaves de API › Nova chave | Configurações › Chaves pessoais › Nova chave pessoal |
| Rotas | POST /api/v1/api-keys | POST /api/v1/me/api-keys |
| Quem pode criar | Quem tem a permissão de gerenciar chaves de API | Qualquer membro ativo, para os próprios scripts |
| Pertence a | Organização | A pessoa que criou, nesta organização |
| Uso típico | Sistemas corporativos | Scripts e automações pessoais |
As duas são usadas do mesmo jeito (Authorization: Bearer sgk_live_...) e obedecem às mesmas regras abaixo.
Permissões: um retrato no momento da criação
Uma chave não herda um papel. Ela recebe uma lista fixa de permissões (permission_keys), escolhida na criação — diretamente ou copiada de um papel com Clonar de um papel (from_role_id na API). A cópia só acontece quando a lista de permissões vai vazia; se você enviar as duas coisas, vale a lista. Consequências:
- Mudar um papel depois não muda as chaves que foram clonadas dele.
- Você só pode dar a uma chave permissões que você mesmo tem naquele momento.
- Uma chave sem permissões autentica, mas recebe
403 permission_deniedem todas as rotas protegidas. - Algumas permissões nunca podem ir para uma chave: gerenciar chaves de API, configurar inteligência artificial, configurar o público e qualquer permissão de plataforma (
400 api_key_forbidden_permission).
Para ajustar uma chave existente, use PATCH /api/v1/api-keys/{código} com os campos que quer mudar:
curl -sS -X PATCH https://api.trust.nearone.com.br/api/v1/api-keys/K7QM \
-H "Authorization: Bearer $TOKEN_DE_UMA_PESSOA" \
-H "Content-Type: application/json" \
-d '{
"permission_keys": ["requests.demands.read", "requests.messages.send"],
"expires_at": "2027-06-30T23:59:59Z",
"allowed_cidrs": ["203.0.113.0/24"]
}'
A resposta é 204 sem corpo. Gerenciar chaves é uma ação de pessoa: uma chave de API não cria, altera nem revoga chaves. Como a permissão de gerenciar chaves nunca pode ser dada a uma chave, a tentativa responde 403.
Validade e redes permitidas
Na criação (POST /api/v1/api-keys) ou depois, por PATCH, você pode restringir a chave:
| Campo | Efeito |
|---|---|
expires_at | Data e hora em que a chave deixa de funcionar. Sem valor, a chave Não expira. |
allowed_cidrs | Lista de redes (por exemplo ["203.0.113.0/24"]) de onde a chave pode ser usada. Lista vazia = qualquer origem. |
Uma chave expirada, revogada ou usada fora das redes permitidas recebe 401 unauthenticated. No backoffice, esses dados aparecem na ficha da chave como Validade e Redes.
Se o seu sistema sai para a internet por IPs fixos, preencha allowed_cidrs. Um segredo vazado fica inútil fora da sua rede.
Chaves não funcionam no navegador
Se uma requisição com chave sgk_ traz o cabeçalho Origin — o que todo navegador faz em chamadas entre domínios —, a API responde:
{
"code": "origin_not_allowed",
"message": "Chaves de API não podem ser usadas a partir de um navegador.",
"request_id": "b41e0c..."
}
com status 401. Não tente contornar isso com um proxy que repasse a chave a partir do navegador: qualquer pessoa que abrisse o site poderia ler o segredo. Exponha ao front-end apenas os dados que o seu backend já buscou.
Rotas que uma chave não alcança
Algumas áreas exigem uma pessoa e respondem 403 actor_not_allowed para chaves:
- login, renovação de sessão, senha, convites e cadastro de segundo fator (
/api/v1/auth/...); - dados e preferências da própria conta: sessões, avatar, e-mail de recuperação, chaves pessoais e conexões MCP (
/api/v1/me/...); - gestão de chaves de API.
Além disso, algumas decisões sensíveis do canal de denúncias são reservadas a pessoas (respondem 403 actor_not_allowed ou 403 requests_api_key_not_allowed), por exemplo: revelar a identidade de quem relatou, exportar o caso, salvar a análise, prorrogar prazo, expurgar por retenção, proteger um caso e conceder acesso nominal a casos protegidos.
Casos protegidos ficam fora do alcance das chaves
Casos da fila restrita só podem ser lidos por pessoas com a permissão de leitura de casos restritos e acesso nominal concedido no caso. Uma chave de API não atende a essa regra, então esses casos não aparecem nas listagens e respondem 404 quando pedidos diretamente. Projete a sua integração sabendo disso: ela enxerga a operação geral do canal, não o conteúdo protegido.
Limite de chamadas
Cada chave tem um limite de requisições por janela de tempo (o padrão é 600 requisições por minuto por chave). Acima disso, a API responde 429 rate_limited. Essa resposta do limite por chave não traz o cabeçalho Retry-After: espere alguns segundos (a janela é de um minuto) e use recuo exponencial nas novas tentativas. Quando outras respostas 429 ou 503 trouxerem Retry-After, respeite o valor indicado.
Revogação
Na ficha da chave, Revogar encerra a chave imediatamente: "a partir daqui, qualquer chamada com o segredo desta chave recebe 401". Pela API, POST /api/v1/api-keys/{código}/revoke (resposta 204). O código e o prefixo continuam visíveis para auditoria.
Não existe "girar" o segredo de uma chave. Para rotacionar: emita uma chave nova com as mesmas permissões, implante o novo segredo no seu sistema, confira o Último uso da chave antiga parar de mudar e, então, revogue-a.
Token de acesso de pessoa
É a credencial que o backoffice usa. Uma integração só deve usá-la se for, ela própria, uma aplicação em que a pessoa entra com as suas credenciais.
Fluxo
1. Login
curl -sS -c cookies.txt https://api.trust.nearone.com.br/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "ana@empresa.com.br", "password": "••••••••", "plane": "organization"}'
{
"access_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"plane": "organization",
"expires_in": 900
}
access_tokené um JWT assinado (algoritmo EdDSA) e de vida curta.expires_ininforma a validade em segundos (15 minutos na configuração padrão).- A resposta também grava um cookie de renovação
HttpOnly,SameSite=Strict, restrito ao caminho/api/v1/auth/refresh, válido por até 30 dias. - E-mail ou senha errados respondem
401 invalid_credentials. Tentativas repetidas para o mesmo e-mail e endereço IP são limitadas (429 rate_limited, 8 tentativas a cada 15 minutos na configuração padrão).
2. Segundo fator (MFA)
Quando a organização exige segundo fator, o login cria a sessão, mas as rotas da organização respondem 403 até a pessoa confirmar o fator:
| Código | Significado |
|---|---|
mfa_challenge_required | A pessoa já tem um fator cadastrado: confirme com POST /api/v1/auth/mfa/challenge |
mfa_enrollment_required | A organização exige um fator e a pessoa ainda não cadastrou nenhum |
curl -sS -X POST https://api.trust.nearone.com.br/api/v1/auth/mfa/challenge \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"method": "totp", "code": "123456"}'
methodaceitatotp(aplicativo autenticador),email(código enviado por e-mail) erecovery(código de recuperação).- Para
email, envie primeiro semcode: a API manda um código de 6 dígitos válido por 10 minutos; depois envie de novo com o código. remember_device: truegrava um cookie de dispositivo confiável por 30 dias, que dispensa o desafio nos próximos logins naquele navegador.- São permitidas 5 tentativas a cada 10 minutos por sessão. Código errado responde
401 mfa_invalid; acima do limite, a resposta é429 rate_limitedcomRetry-After. O envio de códigos por e-mail tem um limite próprio, também de 5 a cada 10 minutos.
Mesmo que a organização não exija MFA para todos, abrir ou operar um caso do canal de denúncias exige que a pessoa tenha um segundo fator confirmado na sessão. Sem isso, a resposta é 403 reporting_case_mfa_required (ou 403 mfa_challenge_required, se o fator existe mas não foi confirmado nesta sessão), e a tentativa fica registrada no log de acesso do caso.
3. Renovação
Antes (ou logo depois) de o token expirar, chame POST /api/v1/auth/refresh enviando o token atual, mesmo expirado, e o cookie de renovação:
curl -sS -b cookies.txt -c cookies.txt -X POST \
https://api.trust.nearone.com.br/api/v1/auth/refresh \
-H "Authorization: Bearer $ACCESS_TOKEN_EXPIRADO"
A cada renovação, o cookie é trocado. Há uma pequena tolerância de alguns segundos para duas renovações simultâneas (por exemplo, duas abas). Fora dela, se um cookie já usado for apresentado de novo, a API entende como sinal de roubo, encerra a sessão e responde 401 session_revoked. Por isso, guarde sempre o cookie mais recente.
4. Encerramento
POST /api/v1/auth/logout encerra a sessão e apaga o cookie de renovação. A pessoa também pode encerrar sessões em Configurações › Segurança.
Diagnóstico de 401 e 403
| Status | code | O que fazer |
|---|---|---|
| 401 | unauthenticated | Confira o cabeçalho Authorization: Bearer .... Para chaves: segredo completo, chave ativa, validade e redes. Para pessoas: renove o token. |
| 401 | origin_not_allowed | Não use chaves sgk_ a partir de navegadores. |
| 401 | session_revoked | A sessão foi encerrada (logout, revogação ou cookie reutilizado). Faça login de novo. |
| 401 | invalid_credentials | E-mail ou senha incorretos no login. |
| 401 | mfa_invalid | Código de segundo fator incorreto. |
| 403 | permission_denied | A credencial não tem a permissão exigida pela rota. |
| 403 | actor_not_allowed | A rota não aceita este tipo de credencial. |
| 403 | mfa_challenge_required | Confirme o segundo fator nesta sessão. |
| 403 | mfa_enrollment_required | Cadastre um segundo fator. |
| 403 | reporting_case_mfa_required | Casos do canal de denúncias exigem segundo fator habilitado. |
| 403 | password_change_required | Troque a senha temporária antes de continuar. |
| 403 | membership_inactive | O vínculo da pessoa com a organização está inativo. |
| 403 | org_suspended | A organização está suspensa. |
| 429 | rate_limited | Reduza o ritmo. Aguarde o tempo de Retry-After quando o cabeçalho vier; sem ele (limite por chave), espere alguns segundos. |
A lista completa está em Erros da API.
Boas práticas
- Guarde segredos em um cofre, nunca no código-fonte, em planilhas ou em mensagens.
- Uma chave por sistema, com o mínimo de permissões.
- Restrinja redes e validade quando possível.
- Monitore o Último uso das chaves e revogue as que não são usadas.
- Registre o
request_idde cada erro: é o que o suporte precisa para encontrar a chamada.