Autenticación
Las requests a la API de Nodda se autentican con una API key en el header Authorization, esquema Bearer:
No hay OAuth ni sesiones para la API: la key es la credencial. Trátala como una contraseña — quien la tenga puede consultar y operar en nombre de tu organización.
Formato del token
- El prefijo
nodda_sk_identifica visualmente la key. - Solo se persiste el hash SHA-256 del token, nunca el valor en claro.
- En los listados verás un
display_prefix(p. ej.nodda_sk_a1B2) para reconocer cada key sin exponer el secreto. - El token completo se muestra una sola vez, en el momento de creación.
La organización se deriva de la key
Cada key pertenece a una sola organización. Nodda resuelve la organización desde la key — no necesitas enviar ningún header adicional de organización.
Cómo obtener una key
Las keys se crean desde el dashboard en app.nodda.cl/settings/api-keys. El endpoint POST /api/api-keys es solo-sesión (requiere estar autenticado en la plataforma, no sirve una API key).
Al crear una key, el token en claro aparece una sola vez en pantalla. Si lo pierdes, debes revocar la key y crear otra.
Qué puede (y qué no) una API key
Una key permite leer y operar sobre las conexiones de su organización, pero no administrar credenciales ni la propia infraestructura de keys:
| Permitido con API key | Solo desde la plataforma (sesión de usuario) |
|---|---|
GET /connections | Crear conexiones (POST /connections) |
GET /connections/{id} | Eliminar conexiones |
POST /connections/{id}/sync | Crear, listar o revocar API keys |
GET /connections/{id}/sync-runs | |
PUT /connections/{id}/schedule | |
GET /external-sources | |
Leer datos proyectados por scope (data_url) |
Usar una API key en un endpoint solo-sesión responde 403 forbidden.
Ciclo de vida de las keys
- Crear — desde el dashboard. El token aparece solo en esa pantalla.
- Listar — el dashboard muestra las keys sanitizadas (solo
display_prefix, sin el token). - Revocar — desde el dashboard. La revocación es inmediata.
- Rotar — crea una key nueva, despliégala y luego revoca la vieja.
Cada key tiene un status:
status | Cuándo |
|---|---|
active | no revocada y no expirada |
revoked | revocada explícitamente |
expired | pasó su expires_at |
Errores de autenticación
| Código | HTTP | Cuándo |
|---|---|---|
unauthorized | 401 | Key inválida, revocada o expirada |
forbidden | 403 | Se usó una API key en un endpoint solo-sesión |
El catálogo completo está en Errores.
Nunca publiques una key en código cliente, repositorios o logs. Si se filtra, revócala de inmediato desde el dashboard.