Autenticação

A API pública do Nobur suporta dois tipos de credenciais, ambas enviadas via header X-API-Key.

Chaves de API (nbr_)

Chaves de API são credenciais de conta de serviço, ideais para integrações servidor-a-servidor. Possuem prefixo nbr_.

Características:

• Vinculadas a uma organização específica
• Possuem escopos de permissão configuráveis
• Não expiram (podem ser revogadas manualmente)
• Ideais para automações, importações e integrações com ERPs

Como criar:

1. Acesse Configurações > Chaves de API na sua organização
2. Clique em Nova Chave de API
3. Configure o nome, papel e escopos desejados
4. Copie a chave gerada (ela não será exibida novamente)

Tokens de Acesso Pessoal (pat_)

Tokens de acesso pessoal representam um usuário específico, herdando suas permissões. Possuem prefixo pat_.

Características:

• Vinculados a um usuário
• Herdam as permissões do usuário no tenant
• Podem acessar múltiplas organizações do mesmo tenant
• Ideais para scripts pessoais e ferramentas de desenvolvimento

Como criar:

1. Acesse Perfil > Tokens de Acesso
2. Clique em Novo Token
3. Configure o nome e as organizações permitidas
4. Copie o token gerado

Enviando Credenciais

Inclua a credencial no header X-API-Key de todas as requisições:

curl -X GET https://api.nobur.com.br/public/v1/me \
  -H "X-API-Key: nbr_sua_chave_aqui"

Header X-Organization-ID

Para tokens de acesso pessoal (PAT) que possuem acesso a múltiplas organizações, use o header X-Organization-ID para especificar a organização desejada:

curl -X GET https://api.nobur.com.br/public/v1/brokers \
  -H "X-API-Key: pat_seu_token_aqui" \
  -H "X-Organization-ID: org_abc123"

Para chaves de API (nbr_), a organização já está vinculada à chave e este header é opcional.

Endpoint /me

Use o endpoint GET /me para verificar se a autenticação está funcionando e obter informações sobre o principal:

curl -X GET https://api.nobur.com.br/public/v1/me \
  -H "X-API-Key: nbr_sua_chave_aqui"

Resposta para chave de API:

{
  "type": "api_key",
  "principal_id": "nbr_abc123",
  "tenant_id": "tnt_abc123",
  "organization_id": "org_abc123",
  "role": "org_editor",
  "scopes": ["brokers:read", "brokers:write", "properties:read"]
}

Resposta para token de acesso pessoal:

{
  "type": "personal_access_token",
  "principal_id": "pat_abc123",
  "user_id": "usr_abc123",
  "email": "usuario@exemplo.com",
  "tenant_id": "tnt_abc123",
  "organization_id": "org_abc123",
  "allowed_organization_ids": ["org_abc123", "org_def456"]
}

Erros de Autenticação

{
  "type": "unauthorized",
  "title": "Authentication Required",
  "status": 401,
  "detail": "authentication required",
  "code": "unauthorized.auth_required",
  "request_id": "req_abc123",
  "timestamp": "2026-02-15T12:00:00Z"
}

Boas Práticas de Segurança

• Nunca exponha chaves no frontend -- use-as apenas em servidores backend
• Use escopos mínimos -- configure apenas as permissões necessárias para a integração
• Rotacione chaves periodicamente -- revogue chaves antigas e crie novas
• Monitore o uso -- verifique os logs de auditoria para detectar acessos não autorizados
• Use variáveis de ambiente -- armazene credenciais em variáveis de ambiente, nunca no código