Autenticação
Cada request à API pública transporta um par de credenciais — nb_pub_* (chave pública) + nb_sec_* (segredo). O segredo é enviado como Bearer token. A credencial tem scope numa única organização + um catálogo de scopes fixo.
Emitir credenciais
- Inicie sessão na sua organização em app.nexbasira.com.
- Vá a Admin → Credenciais da API.
- Clique em Emitir credencial, escolha um nome + scopes, confirme.
- Copie o par
nb_pub_*+nb_sec_*. O segredo é mostrado uma única vez. Guarde-o de imediato no seu gestor de segredos — nós mantemos apenas um hash SHA-256 do nosso lado.
Usar a credencial
Authorization: Bearer nb_sec_AbCdEf... A chave pública (nb_pub_*) identifica a credencial nos nossos logs + aparece no cabeçalho NB-Credential-Id das entregas de webhook. O segredo autentica.
curl https://app.nexbasira.com/api/v1/public/sessions \
-H "Authorization: Bearer nb_sec_..."Catálogo de scopes
Cada credencial é criada com um conjunto de scopes explícito. Os requests fora desses scopes devolvem 403. O catálogo de scopes é fixo (sem scopes personalizados na v1):
| Scope | Concede |
|---|---|
sessions:read | Listar + obter sessões |
sessions:write | Criar sessões + terminá-las |
participants:read | Listar participantes numa sessão |
participants:write | Emitir convites de utilizador de terreno |
evidence:read | Listar + obter linhas de prova + URLs de transferência assinados |
recordings:read | Ler metadados de artefactos de gravação + URLs de transferência |
audit:read | Ler a cadeia de auditoria por sessão + coordenadas de ancoragem na TSA |
webhooks:read | Listar endpoints de webhook registados + registo de entregas |
webhooks:write | Registar / rodar-segredo / eliminar endpoints de webhook |
branding:read | Ler a marca da organização (logótipo / cores / rodapé de PDF) |
branding:write | Alterar a marca da organização |
org:read | Ler metadados da organização |
whiteboards:read | Listar quadros brancos por sessão |
Rotação
Para rodar sem downtime:
- Emita uma nova credencial com o mesmo conjunto de scopes.
- Implemente o novo segredo na sua aplicação.
- Verifique que a nova credencial está a receber tráfego (Admin → Credenciais da API mostra o timestamp de última utilização).
- Revogue suavemente a credencial antiga. Os requests existentes que a usam devolvem 401; o trilho de auditoria das chamadas anteriores permanece intacto.
Verificação em tempo constante
No backend, os segredos são guardados como SHA-256(secret + SECRET_KEY_pepper) e comparados em tempo constante (hmac.compare_digest). Um dump de hashes vazado não pode ser submetido a brute-force para obter o texto simples sem também quebrar o pepper.
O que esta credencial NÃO concede
- Acesso à administração da SPA — isso é separado (login de operador + RBAC).
- Entrada do lado do terreno — essa usa URLs assinados de uso único emitidos via
sessions.invite(). - Aprovisionamento SCIM — usa um bearer token por organização separado, ver aprovisionamento SCIM.
- Assinatura de webhook — isso é feito com o segredo
whsec_*por endpoint, ver Webhooks.
Trilho de auditoria
Cada chamada à API é registada com a chave pública da credencial + o endpoint + estado. As operações que alteram estado escrevem adicionalmente linhas de auditoria na organização afetada. O administrador pode ver a atividade da credencial em Admin → Credenciais da API → [credencial] → Atividade.