Saltearse al contenido

API keys y tokens de gestión

NamiDB Cloud tiene dos tipos de credenciales. Cada una funciona solo con su propia API.

API keyToken de gestión
Formanmdb_live_…nmdb_mgmt_…
Se usa paraEjecutar Cypher: HTTP, Bolt, MCPGestionar la organización: la API de gestión, la CLI, Terraform
Endpointhttps://db.namidb.comhttps://app.namidb.com/api/v1
PermisosUn rol (lectura y escritura o solo lectura) y un conjunto de bases de datosUn scope (read, write o admin)
Quién la creaOwners, admins y developers (consola, API, CLI, Terraform)Owners y admins, en la consola, con autenticación en dos pasos
Por organización50 activas25 activos
Clase del SDKNamiDBManagementClient

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.

ScopePermite
readTodos 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
writeread, más crear y eliminar bases de datos, backups, restauraciones, clones y exportaciones, y abrir y responder tickets de soporte
adminwrite, 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.