Autenticação
A API de integração Nearone usa chaves de API enviadas como
bearer token no cabeçalho Authorization.
Gerar uma chave
As chaves são criadas na aplicação Nearone em
Configurações → Chaves de API (/settings/api-keys).
Ao criar, você define:
| Campo | Descrição |
|---|---|
name | Nome de identificação da chave. |
scopes | Permissões concedidas (ver abaixo). |
environment | live ou test. |
expires_at | Expiração opcional. |
ip_allowlist | IPs autorizados (opcional). |
rate_limit_per_minute | Limite de requisições/min (opcional). |
:::warning Segredo exibido uma única vez
O valor completo da chave (api_key) é mostrado apenas no momento da criação
ou rotação. Guarde-o com segurança — a Nearone armazena somente o hash.
:::
Usar a chave
Envie a chave como bearer token:
curl https://api.nearone.com.br/api/integrations/v1/companies \
-H "Authorization: Bearer no_live_xxxxxxxxxxxxxxxxxxxx"
O prefixo identifica o ambiente:
no_live_…— ambiente de produção (live)no_test_…— ambiente de teste (test)
Escopos
Permissões seguem o formato <recurso>:<ação>. Curingas por recurso
(companies:*) são aceitos.
| Escopo | Permite |
|---|---|
companies:read | Ler empresas. |
companies:write | Criar e atualizar empresas. |
companies:* | Todas as ações sobre empresas. |
participants:read | Ler participantes (colaboradores). |
participants:write | Criar e atualizar participantes. |
participants:* | Todas as ações sobre participantes. |
Escopos de recursos diferentes são independentes: companies:* não concede
nada sobre participants, e vice-versa.
Uma requisição sem o escopo necessário retorna 403 com error: insufficient_scope.
Erros de autenticação
| Status | Causa |
|---|---|
401 | Cabeçalho Authorization ausente, chave inválida, revogada ou expirada. |
403 | IP fora da allowlist ou escopo insuficiente. |
429 | Limite de taxa excedido. |