Pular para o conteúdo principal

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.

CredencialFormatoQuem usaQuando escolher
Chave de APIsgk_live_<prefixo>_<segredo>Sistemas da empresa (servidor para servidor)Integrações permanentes: ERP, BI, RH, automações
Token de acesso de pessoaJWT de curta duraçãoO backoffice, em nome de quem fez loginAplicações em que uma pessoa entra com e-mail e senha
Token MCPJWT emitido via OAuthAssistentes de IA compatíveis com MCPQuando uma IA deve agir em nome de uma pessoa (veja MCP)
Regra prática

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. Chaves sgk_test_ pertencem a ambientes de teste e são recusadas em produção com 401.
  • 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 listagem GET /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çãoChave pessoal
Onde criarIntegração › Chaves de API › Nova chaveConfigurações › Chaves pessoais › Nova chave pessoal
RotasPOST /api/v1/api-keysPOST /api/v1/me/api-keys
Quem pode criarQuem tem a permissão de gerenciar chaves de APIQualquer membro ativo, para os próprios scripts
Pertence aOrganizaçãoA pessoa que criou, nesta organização
Uso típicoSistemas corporativosScripts 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_denied em 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:

CampoEfeito
expires_atData e hora em que a chave deixa de funcionar. Sem valor, a chave Não expira.
allowed_cidrsLista 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.

Restrinja sempre que puder

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.

Rotação de segredo

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_in informa 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ódigoSignificado
mfa_challenge_requiredA pessoa já tem um fator cadastrado: confirme com POST /api/v1/auth/mfa/challenge
mfa_enrollment_requiredA 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"}'
  • method aceita totp (aplicativo autenticador), email (código enviado por e-mail) e recovery (código de recuperação).
  • Para email, envie primeiro sem code: 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: true grava 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_limited com Retry-After. O envio de códigos por e-mail tem um limite próprio, também de 5 a cada 10 minutos.
Casos do canal de denúncias exigem segundo fator

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​

StatuscodeO que fazer
401unauthenticatedConfira o cabeçalho Authorization: Bearer .... Para chaves: segredo completo, chave ativa, validade e redes. Para pessoas: renove o token.
401origin_not_allowedNão use chaves sgk_ a partir de navegadores.
401session_revokedA sessão foi encerrada (logout, revogação ou cookie reutilizado). Faça login de novo.
401invalid_credentialsE-mail ou senha incorretos no login.
401mfa_invalidCódigo de segundo fator incorreto.
403permission_deniedA credencial não tem a permissão exigida pela rota.
403actor_not_allowedA rota não aceita este tipo de credencial.
403mfa_challenge_requiredConfirme o segundo fator nesta sessão.
403mfa_enrollment_requiredCadastre um segundo fator.
403reporting_case_mfa_requiredCasos do canal de denúncias exigem segundo fator habilitado.
403password_change_requiredTroque a senha temporária antes de continuar.
403membership_inactiveO vínculo da pessoa com a organização está inativo.
403org_suspendedA organização está suspensa.
429rate_limitedReduza 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​

  1. Guarde segredos em um cofre, nunca no código-fonte, em planilhas ou em mensagens.
  2. Uma chave por sistema, com o mínimo de permissões.
  3. Restrinja redes e validade quando possível.
  4. Monitore o Último uso das chaves e revogue as que não são usadas.
  5. Registre o request_id de cada erro: é o que o suporte precisa para encontrar a chamada.