Tokens de API

Un token de API es necesario cuando a /api/v1 accede no un navegador, sino un script, CI, un servicio externo u otra automatización. Sustituye la sesión del navegador en las peticiones API y actúa en nombre del usuario que lo emitió.

El token no crea un rol separado ni otorga permisos especiales. Si el usuario tiene acceso a la organización, la petición API con su token obtiene el mismo acceso; si no tiene acceso, el token no lo añadirá.

Qué proporciona un token

El token personal habilita el acceso bearer a las rutas protegidas /api/v1. Se envía en el encabezado HTTP:

Authorization: Bearer <token>

A partir de ahí, la petición pasa las mismas verificaciones que un usuario normal en la interfaz: pertenencia a la organización, rol y permisos para la acción concreta. Por eso es práctico usar el token para scripts, integraciones y exportaciones periódicas, pero debe almacenarse como una contraseña.

En la versión actual, los tokens no se configuran con scopes individuales. Cada token emitido actúa con el acceso completo de su propietario dentro de sus permisos reales. Si necesitas un agente de IA externo con scopes limitados, usa una conexión MCP en lugar de un token de API personal.

Cómo emitir

Abre el perfil dentro de la organización y ve a la sección Tokens de API. Indica un nombre descriptivo: por ejemplo, el nombre del script, servicio o entorno donde se usará el token.

La fecha de caducidad es opcional. Si no se especifica, el token será válido hasta su revocación manual. Si se indica, después de esa fecha el token dejará de proporcionar acceso y desaparecerá de la lista de activos.

Tras la emisión, el secreto completo se muestra una sola vez. Cópialo de inmediato y guárdalo en un almacenamiento seguro. Más tarde, la plataforma mostrará solo el nombre, la fecha de creación, la fecha de caducidad y la hora del último uso; no se puede recuperar el texto completo del token.

Cómo usar de forma segura

Crea un token separado para cada script o servicio. De este modo, por su nombre en la lista se entiende dónde se usa y se puede revocar sin detener otras integraciones.

No incluyas el token en código público, documentación, tareas, chats ni JavaScript del lado del cliente. Para integraciones en el servidor, almacénalo en variables de entorno o en un gestor de secretos.

Si el token pudo haberse filtrado, revócalo y emite uno nuevo. La revocación surte efecto de inmediato: el antiguo encabezado bearer deja de pasar la autenticación.

Lista y revocación

En la página de Tokens de API se muestran solo los tokens activos del usuario actual. En la lista se ven el nombre, la fecha de creación, la fecha de caducidad y el último uso. Los tokens de otros usuarios no se muestran aquí.

Para cerrar el acceso, haz clic en Revocar junto al token deseado y confirma la acción. Esto elimina únicamente ese token; la cuenta de usuario y el resto de tokens permanecen.

Un token caducado no necesita ser revocado manualmente por seguridad de acceso: ya no funciona. Sin embargo, para una nueva integración es necesario emitir un nuevo token y reemplazar el secreto en el servicio que realiza las peticiones API.