Saltar a contenido

🔐 Autenticación y permisos

Cada petición a la API pública lleva una credencial en la cabecera Authorization, con el formato Bearer <credencial>. Lo que puede hacer la petición depende de la credencial: de los scopes que tiene y del rol con el que actúa.

Tipos de credencial

La API acepta dos tipos de credencial:

Clave API Token de usuario
Representa Al workspace, no a una persona. A un usuario concreto en un workspace concreto.
Quién la obtiene Un administrador, en Configuración > Claves API. Una aplicación a la que Zinkee se la emite para actuar en nombre del usuario.
Permisos Todos: los cuatro scopes y el rol Administrador. Los del rol del usuario, que se comprueba en cada petición.
Duración 30 días, 90 días, 1 año o sin fecha de expiración. Corta, de minutos.
Autor de los cambios en el historial API - <nombre del workspace> El email del usuario.

Claves API

Las claves API siguen siendo, como hasta ahora, credenciales del workspace con todos los permisos. No dependen del rol de ningún usuario: quien tenga una puede consultar y modificar todo el workspace, también su estructura. Son la credencial que debes usar en tus integraciones y scripts.

Consulta cómo crearlas y revocarlas en Claves API.

Tokens de usuario

Un token de usuario es la credencial con la que una aplicación actúa en nombre de un usuario y con su rol: con él no se puede hacer nada que ese rol no permita.

  • No puedes crear tokens de usuario para tus integraciones: usa una clave API.
  • El rol se comprueba en cada petición. Si un administrador cambia el rol del usuario o lo da de baja del workspace, el cambio se aplica desde su siguiente petición, aunque el token no haya caducado.
  • Solo vale para la API V2, las rutas que empiezan por /api/v2.

Los asistentes de IA que conectas a Zinkee, como Claude o ChatGPT, trabajan con tokens de usuario. Consulta cómo conectarlos en Asistentes de IA.

Scopes y rol mínimo

Cada operación de la API exige un scope y un rol mínimo. La petición se ejecuta solo si la credencial tiene ese scope y el rol actual llega a ese rol mínimo.

Scope Rol mínimo Qué permite
records:read Estándar Consultar registros, sus comentarios, su historial y sus archivos.
records:write Estándar Crear, editar y borrar registros, comentar y subir archivos.
workspace:read Estándar Leer la definición del workspace.
workspace:admin Administrador Cambiar la definición del workspace.

En detalle:

  • records:read permite listar, obtener y filtrar registros, leer sus comentarios y su historial, descargar archivos y consultar el uso del almacenamiento.
  • records:write permite crear, editar y borrar registros, comentar, y subir o borrar archivos.
  • workspace:read permite leer tablas y campos, carpetas, navegación, espacio de equipo, interfaces, automatizaciones, conexiones, plugins y plantillas de documento, y la lista de miembros del workspace (email y alias).
  • workspace:admin permite cambiar la definición del workspace: crear, editar y borrar tablas, campos, carpetas, interfaces, automatizaciones, conexiones y plantillas de documento, y organizar la navegación y el espacio de equipo. También permite vaciar tablas y recalcular fórmulas.

De las 109 operaciones de la API V2, 72 exigen workspace:admin y el rol Administrador. Las otras 37 están al alcance de un usuario estándar.

Ten en cuenta que:

  • Estándar es cualquier miembro activo del workspace. El propietario de la organización que no tiene el rol Administrador en el workspace también cuenta como Estándar.
  • Administrador es quien tiene el rol Administrador en el workspace.
  • Los scopes no se incluyen entre sí: records:write no da records:read.
  • Borrar registros exige records:write; vaciar una tabla entera, workspace:admin.
  • Las plantillas de documento se consultan y se descargan con workspace:read. Crearlas, editarlas, borrarlas y gestionar sus archivos exige workspace:admin.
  • El endpoint de webhook de una automatización exige workspace:admin también para consultarlo, porque su URL permite disparar la automatización.

Cada credencial recibe estos scopes:

Credencial Scopes
Clave API Los cuatro, con el rol Administrador.
Token de usuario de un administrador Los cuatro.
Token de usuario de un usuario estándar records:read, records:write y workspace:read. Nunca workspace:admin.

En la referencia de la API, cada operación indica el scope que exige. En la especificación OpenAPI, el scope está en security y el rol mínimo en x-zinkee-min-role: todas las operaciones con workspace:admin exigen el rol Administrador, y las demás, el rol Estándar.

Errores 401 y 403

La API distingue dos casos:

  • 401 Unauthorized: la credencial no vale. Necesitas otra.
  • 403 Forbidden: la credencial vale, pero no tienes permiso para esta operación.

Decide por el código de estado, no por el motivo

Trata cualquier 401 como «la credencial no vale» y cualquier 403 como «no tienes permiso», sea cual sea su reason, también si recibes un motivo que no aparece en esta página. El motivo solo explica por qué.

En los dos casos, la petición no se ejecuta ni consume cuota del límite de peticiones, y la respuesta no incluye las cabeceras RateLimit. El cuerpo tiene el formato habitual de los errores de la API: el campo reason indica el motivo concreto; message y action describen el error en inglés y su texto puede cambiar.

401: la credencial no vale

El motivo depende del tipo de credencial y de lo que falla:

reason Cuándo ocurre Qué hacer
invalid_token Falta la credencial o no se envía como Bearer, la credencial es de un tipo que la API no reconoce, o el token de usuario no es válido: está mal formado, su firma no es correcta o no se emitió para esta API o para este workspace. Revisa la cabecera Authorization y envía una credencial válida.
invalid La clave API, o cualquier credencial que no sea un token de usuario, está mal formada o incompleta, o su firma no es correcta. Suele pasar al copiar la clave sin algún carácter. Copia de nuevo la clave completa o crea una nueva.
expired La clave API o el token ha caducado. Crea una clave API nueva o consigue un token nuevo.
invalid_workspace_token La clave API está revocada o ya no es válida para su workspace. Crea una clave API nueva.
membership_revoked El usuario del token de usuario ya no tiene acceso al workspace: se le ha dado de baja, está inactivo o se ha eliminado. Pide acceso a un administrador del workspace.
wrong_type El token lo ha firmado Zinkee, pero la API no acepta su tipo. Envía una clave API.
wrong_audience El token de ejecución de un plugin no se emitió para esta API. Envía una clave API.

La respuesta incluye la cabecera WWW-Authenticate: Bearer error="invalid_token" con cualquiera de estos motivos. Repetir la petición con la misma credencial da el mismo error.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer error="invalid_token"

{
  "status": 401,
  "error": "UNAUTHORIZED",
  "reason": "invalid_workspace_token",
  "message": "Invalid token",
  "action": "Verify workspace token/key validity and retry.",
  "retryable": false,
  "path": "/api/v2/schemas",
  "requestId": "2e7b5d1f-9a3c-4f6e-b8d0-4c1a7e9f3b52",
  "timestamp": "2026-10-28T10:15:00Z"
}

403: la credencial no alcanza

  • insufficient_scope: el token no tiene el scope de la operación. Es lo que recibe, por ejemplo, el token de un usuario estándar al intentar crear una tabla. La cabecera WWW-Authenticate indica el scope que exige la operación: Bearer error="insufficient_scope", scope="workspace:admin".
  • insufficient_role: el token tiene el scope, pero el rol actual del usuario no llega al rol mínimo. Ocurre, por ejemplo, si un administrador le cambia el rol a Estándar después de emitirse el token. La cabecera es Bearer, sin error: pedir más scopes no lo arregla.
  • user_token_not_supported: la operación solo acepta credenciales del workspace, como las claves API. Ocurre fuera de la API V2 y la respuesta no lleva la cabecera WWW-Authenticate.

Las claves API tienen todos los scopes y el rol Administrador, así que no reciben estos errores. No repitas la petición tal cual: necesita otra credencial u otro rol.

HTTP/1.1 403 Forbidden
Content-Type: application/json
WWW-Authenticate: Bearer error="insufficient_scope", scope="workspace:admin"

{
  "status": 403,
  "error": "FORBIDDEN",
  "reason": "insufficient_scope",
  "message": "This operation requires the scope workspace:admin.",
  "action": "Use a credential with the required scope.",
  "retryable": false,
  "path": "/api/v2/automations",
  "requestId": "4e8b2d6f-0a3c-4d9e-b7f1-6c2a8e4d0b53",
  "timestamp": "2026-10-28T10:15:00Z"
}

Ejemplo con una clave API

Para listar las tablas del workspace con una clave API guardada en la variable de entorno ZINKEE_API_KEY:

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

Consulta todos los endpoints, con el scope que exige cada uno, en la referencia de la API.