Saltar a contenido

🔑 Claves API

Una clave API permite que una aplicación, un script o una integración externa trabaje con un workspace a través de la API pública de Zinkee. Cada clave pertenece a un único workspace.

Antes de empezar

  • Necesitas el rol Administrador en el workspace. Los usuarios estándar no ven la sección Claves API.
  • La clave no depende de los permisos de ningún usuario: quien la tenga puede consultar y modificar el workspace a través de la API. Trátala como una contraseña.

Crear una clave API

  1. Entra en Zinkee y selecciona el workspace.
  2. Abre Configuración con el icono del engranaje de la barra lateral.
  3. En Espacios de trabajo, ve a Claves API.
  4. Pulsa Crear clave API.
  5. En Nombre de la clave API, escribe un nombre que identifique su uso, por ejemplo Integración ERP o Informes semanales.
  6. En Expiración, elige 30 días, 90 días, 1 año o Sin fecha de expiración. Por defecto se propone 1 año. Con Sin fecha de expiración, la tabla muestra en Expira el una fecha dentro de 100 años.
  7. Pulsa Crear clave.
  8. En Clave API creada, pulsa Copiar clave API y guárdala en un lugar seguro, como un gestor de contraseñas o de secretos.
  9. Pulsa Listo.

Ventana Crear clave API con el nombre Integración ERP y la expiración de 1 año

Ventana Clave API creada con una clave de ejemplo y los botones Copiar clave API y Listo

La clave solo se muestra una vez

Después de cerrar la ventana Clave API creada no podrás volver a verla completa. Si la pierdes, crea una clave nueva y revoca la anterior.

Consultar las claves del workspace

La sección Claves API muestra todas las claves del workspace:

Columna Qué indica
Nombre El nombre que se dio a la clave al crearla.
Clave enmascarada Los primeros y últimos caracteres de la clave, para reconocerla sin mostrarla.
Usuario creador El email del administrador que la creó.
Fecha creación Cuándo se creó.
Expira el Cuándo deja de funcionar.
Estado Activo, Revocada o Expirada.
Acciones Revocar, solo en las claves activas.

Sección Claves API de Configuración con una clave revocada y otra activa

Una clave Expirada deja de funcionar al llegar a su fecha de expiración. Para renovarla, crea una clave nueva, actualiza la integración que la usa y revoca la anterior si todavía no ha expirado.

Revocar una clave

Revoca una clave cuando ya no se use o si crees que alguien más ha podido obtenerla.

  1. En Configuración > Claves API, localiza la clave.
  2. Pulsa Revocar.
  3. Confirma con Revocar.

La clave deja de funcionar inmediatamente y queda en la tabla con el estado Revocada. Una clave revocada no se puede volver a activar: si la integración la sigue necesitando, crea una clave nueva.

Usar la clave en la API

Envía la clave en la cabecera Authorization de cada petición, con el formato Bearer <clave>. Por ejemplo, para listar las tablas del workspace:

curl https://api-z2.zinkee.com/api/v2/schemas   
  --header "Authorization: Bearer $ZINKEE_API_KEY"

En este ejemplo, la clave se lee de la variable de entorno ZINKEE_API_KEY para no escribirla directamente en el comando. Si la clave está revocada o ha expirado, la API responde con el código 401.

Consulta todos los endpoints disponibles en la referencia de la API.

✅ Buenas prácticas

  • Crea una clave distinta para cada integración, con un nombre descriptivo. Así podrás revocar una sin afectar a las demás.
  • Elige la expiración más corta que permita tu integración.
  • No compartas la clave por correo o chat ni la incluyas en el código fuente.