API keys y tokens de gestión
NamiDB Cloud tiene dos tipos de credenciales. Cada una funciona solo con su propia API.
| API key | Token de gestión | |
|---|---|---|
| Forma | nmdb_live_… | nmdb_mgmt_… |
| Se usa para | Ejecutar Cypher: HTTP, Bolt, MCP | Gestionar la organización: la API de gestión, la CLI, Terraform |
| Endpoint | https://db.namidb.com | https://app.namidb.com/api/v1 |
| Permisos | Un rol (lectura y escritura o solo lectura) y un conjunto de bases de datos | Un scope (read, write o admin) |
| Quién la crea | Owners, admins y developers (consola, API, CLI, Terraform) | Owners y admins, en la consola, con autenticación en dos pasos |
| Por organización | 50 activas | 25 activos |
| Clase del SDK | NamiDB | ManagementClient |
Ambas se muestran una sola vez, cuando se crean. NamiDB guarda solo un hash con clave, así que nadie (ni siquiera NamiDB) puede volver a mostrártelas. ¿Perdiste una? Revócala y crea otra.
Guárdalas en un gestor de secretos o en variables de entorno del lado del servidor, nunca en el control de versiones, y nunca incluyas una key de lectura y escritura en código de navegador o de una app móvil.
API keys
Créalas en API keys → Create key, con POST /api-keys,
namidb keys create o el recurso de Terraform namidb_api_key. Una key tiene:
- Un rol. Read & write ejecuta cualquier sentencia. Read only solo
ejecuta consultas: el propio motor rechaza las escrituras
(
403 read_only_key), tanto en HTTP como en Bolt y MCP. - Bases de datos. All databases (incluidas las que se creen después), o
una lista. Una petición a cualquier otra base de datos se rechaza
(
403 database_not_in_scope). - Un vencimiento. Nunca, 7 días, 30 días, 90 días (por defecto) o 1 año; con la API, cualquier momento dentro de 2 años. Recibes un email 7 días y 1 día antes de que una key venza.
- Una IP allowlist opcional propia. Consulta IP allowlists.
La consola lista cada key con su prefijo, sus últimos cuatro caracteres, su rol, sus bases de datos, su vencimiento y cuándo se usó por última vez.
Rotar una key
Rotate emite una key nueva con el mismo nombre, rol, bases de datos e IP
allowlist, y mantiene funcionando la anterior durante un periodo de
solapamiento que eliges: 1, 7 (por defecto) o 30 días. Despliega la key nueva
durante el solapamiento; la anterior deja de funcionar sola al final. Con la
API: POST /api-keys/{id}/rotate (overlap_days); la respuesta contiene el
nuevo token y previous_key.expires_at.
Revocar una key
La revocación se aplica en toda la API de datos en unos dos segundos, incluidas las sesiones Bolt abiertas. Las keys revocadas y vencidas siguen apareciendo en la lista (con su estado) como registro.
Política de vida útil de las keys
Los owners y admins pueden limitar cuánto tiempo pueden vivir las keys nuevas:
7, 30, 90, 180 o 365 días (API keys → Lifetime policy). Las keys nuevas y
las rotaciones deben vencer dentro de ese plazo (422 lifetime_policy en caso
contrario); los tokens de gestión siguen la misma política. Las keys existentes
no se modifican.
Cuando la persona que la creó se va
Las API keys pertenecen a la organización, no a una persona: siguen funcionando cuando el miembro que las creó se va o elimina su cuenta. Revisa las keys cuando alguien se va, y rota las que podría haber copiado.
Tokens de gestión
Créalos en Settings → Management API (owners y admins, con autenticación en
dos pasos en tu cuenta). Un token admin también puede emitir tokens para
otras herramientas a través de la
API de gestión,
namidb tokens create en la CLI o
el recurso namidb_management_token de
Terraform, por
ejemplo un token write de corta duración para un job de CI.
| Scope | Permite |
|---|---|
read | Todos los GET excepto invitaciones y tokens de gestión: la organización, bases de datos, backups, restauraciones, clones, exportaciones y sus archivos, metadatos de las API keys, IP allowlists, uso, miembros, tickets de soporte |
write | read, más crear y eliminar bases de datos, backups, restauraciones, clones y exportaciones, y abrir y responder tickets de soporte |
admin | write, más crear, rotar y revocar API keys, entradas de IP allowlists, quitar miembros, y gestionar invitaciones y tokens de gestión |
- Nunca más que quien lo creó. Un token funciona solo mientras quien lo
creó siga siendo owner o admin de la organización (y, cuando la organización
lo exige, siga usando autenticación en dos pasos o SSO). De lo contrario
responde
403 token_inactive. Los tokens nunca otorgan ni quitan el rol de owner. - Tokens creados por tokens. Un token creado a través de la API, la CLI o Terraform actúa por la misma persona que el token que lo creó, nunca tiene un scope más amplio y nunca dura más que él. Funciona solo mientras funcione ese token: revocar el token que lo creó revoca todo lo que creó, y cuando vence o queda inactivo, también lo hacen los tokens que creó. La consola muestra qué token creó cada uno.
- Vencimiento: 30 días, 90 días, un año o nunca, dentro de la política de vida útil de keys de la organización.
- Visibilidad: la consola muestra el scope de cada token, quién lo creó, su vencimiento, y cuándo y desde qué dirección se usó por última vez.
- Auditoría: los cambios hechos con un token aparecen en el registro de auditoría como Token “name”.
- La revocación se aplica en la siguiente petición del token.
Otras credenciales
- Tokens de SCIM (
nmdb_scim_…) permiten que tu proveedor de identidad aprovisione miembros. Se crean en la página de Single sign-on y solo funcionan en el endpoint de SCIM. Consulta SSO y SCIM. - Secretos de firma de webhooks (
whsec_…) firman los eventos que NamiDB te envía. Consulta Alertas y webhooks.