Autenticación
Cada petición a la API pública lleva un par de credenciales: nb_pub_* (clave pública) + nb_sec_* (secreto). El secreto se envía como token Bearer. La credencial está limitada a una sola organización + un catálogo de ámbitos fijo.
Emisión de credenciales
- Inicie sesión en su organización en app.nexbasira.com.
- Vaya a Admin → Credenciales de API.
- Haga clic en Emitir credencial, elija un nombre + ámbitos y confirme.
- Copie el par
nb_pub_*+nb_sec_*. El secreto se muestra exactamente una vez. Guárdelo en su gestor de secretos de inmediato; nosotros solo conservamos un hash SHA-256 de nuestro lado.
Uso de la credencial
Authorization: Bearer nb_sec_AbCdEf... La clave pública (nb_pub_*) identifica la credencial en nuestros registros + aparece en la cabecera NB-Credential-Id de las entregas de webhook. El secreto autentica.
curl https://app.nexbasira.com/api/v1/public/sessions \
-H "Authorization: Bearer nb_sec_..."Catálogo de ámbitos
Cada credencial se crea con un conjunto de ámbitos explícito. Las peticiones fuera de esos ámbitos devuelven 403. El catálogo de ámbitos es fijo (sin ámbitos personalizados en la v1):
| Ámbito | Concede |
|---|---|
sessions:read | Listar + recuperar sesiones |
sessions:write | Crear sesiones + finalizarlas |
participants:read | Listar los participantes de una sesión |
participants:write | Emitir invitaciones de usuario de campo |
evidence:read | Listar + recuperar filas de pruebas + URLs de descarga firmadas |
recordings:read | Leer los metadatos de los artefactos de grabación + URLs de descarga |
audit:read | Leer la cadena de auditoría por sesión + las coordenadas del anclaje TSA |
webhooks:read | Listar los endpoints de webhook registrados + registro de entregas |
webhooks:write | Registrar / rotar secreto / eliminar endpoints de webhook |
branding:read | Leer la marca de la organización (logotipo / colores / pie de página del PDF) |
branding:write | Mutar la marca de la organización |
org:read | Leer los metadatos de la organización |
whiteboards:read | Listar pizarras por sesión |
Rotación
Para rotar sin interrupciones:
- Emita una nueva credencial con el mismo conjunto de ámbitos.
- Despliegue el nuevo secreto en su aplicación.
- Verifique que la nueva credencial está recibiendo tráfico (Admin → Credenciales de API muestra la marca de tiempo de último uso).
- Revoque de forma suave la credencial antigua. Las peticiones existentes que la usen devuelven 401; la cadena de auditoría de llamadas pasadas permanece intacta.
Verificación en tiempo constante
En el backend, los secretos se almacenan como SHA-256(secret + SECRET_KEY_pepper) y se comparan en tiempo constante (hmac.compare_digest). Un volcado de hashes filtrado no puede descifrarse por fuerza bruta hasta el texto plano sin romper también el pepper.
Lo que esta credencial NO concede
- Acceso de administrador a la SPA: es independiente (inicio de sesión de operador + RBAC).
- Unión del lado de campo: esta usa URLs firmadas de un solo uso emitidas mediante
sessions.invite(). - Aprovisionamiento SCIM: usa un token bearer separado por organización, consulte Aprovisionamiento SCIM.
- Firma de webhooks: se realiza con el secreto
whsec_*por endpoint, consulte Webhooks.
Cadena de auditoría
Cada llamada a la API se registra con la clave pública de la credencial + el endpoint + el estado. Las operaciones que mutan estado escriben además filas de auditoría en la organización afectada. El administrador puede ver la actividad de la credencial en Admin → Credenciales de API → [credencial] → Actividad.