Autenticación

Las dos credenciales de la API, y cómo crear, guardar, rotar y revocar un token de API.

Aquí verás qué credencial te conviene, cómo crear un token de API, dónde guardarlo, cómo rotarlo y revocarlo, y qué significa un 401.

Dos credenciales

Las dos se envían igual: Authorization: Bearer fluenta_live_….

	Token de API	Conexión
Quién la crea	Tú, a mano, en «Configuración» → «Tokens de API»	Una aplicación de IA, como Claude o ChatGPT, cuando pulsas «Permitir»
Para qué sirve	Tus propios programas	Usar Fluenta desde la aplicación de IA, por MCP, en `https://app.fluenta.io/mcp`
Planes	Light y Pro	Pro: es la función «Conectar con IA»
Cómo termina	Vence, o pulsas «Revocar»	Pulsas «Desconectar»

Las dos actúan como tú: llegan a tus organizaciones, con tu rol. GET /me dice cuál presentaste en credential.kind: personal es un token de API y oauth es una conexión.

Usa un token de API para un programa tuyo: un script, un reporte semanal o una hoja de cálculo. Usa una conexión cuando quien pregunta es una aplicación de IA: mira IA.

Crear un token

Entra a app.fluenta.io y abre «Configuración» → «Tokens de API».
Pulsa «Crear token».
Escribe un «Nombre» que te diga dónde lo usas. Admite hasta 64 caracteres.
En «Permisos», «Leer» viene siempre. Marca «Gestionar el Programa» solo si el programa va a escribir: mira Permisos.
Elige el «Vencimiento»: «Nunca», «30 días», «90 días» o «1 año».
Pulsa «Crear token» y copia el token con «Copiar token».

El token se muestra una sola vez. Fluenta guarda solo su hash, así que no puede mostrártelo de nuevo: si lo pierdes, crea otro.

Puedes tener hasta 10 tokens activos y crear hasta 10 por hora.

Enviar el token

curl https://api.fluenta.io/v1/external/me \
  -H 'Authorization: Bearer fluenta_live_xxxxxxxxxxxxxxxx'

Guardar el token

Guárdalo solo del lado del servidor: en una variable de entorno o en el gestor de secretos de tu plataforma.
No lo pongas en código que corre en un navegador ni lo subas a un repositorio.
No lo pongas en una URL: la API solo lo lee del encabezado Authorization.
Usa un token por programa. Así revocas uno sin detener los demás.
«Tus tokens» muestra los primeros 16 caracteres de cada uno. Sirven para distinguirlos; no alcanzan para autenticarse.

Un token que no vence sirve hasta que lo revoques. Restablecer tu contraseña no revoca tus tokens.

Rotar un token

No hay una acción de rotar:

Crea un token nuevo con los mismos permisos.
Cambia el secreto en tu programa y despliégalo.
Mira «Último uso» del token viejo en «Tus tokens» para confirmar que ya nadie lo usa.
Pulsa «Revocar» en el token viejo.

Un token no gana permisos después de creado. Si necesitas «Gestionar el Programa», crea uno nuevo.

Revocar un token

Pulsa «Revocar» en la fila del token y confirma. El efecto es inmediato: la siguiente solicitud con ese token responde 401.

Vencimiento

GET /me responde cuándo vence en credential.expiresAt (ISO 8601, UTC). Es null en un token que no vence. Después de esa fecha el token responde 401 y no se puede renovar: crea otro.

Qué significa un 401

{
  "statusCode": 401,
  "code": "INVALID_API_TOKEN",
  "message": "La credencial no es válida o venció. Si es una app conectada, vuelve a conectarla; si es un token de API, crea uno nuevo en Configuración."
}

La respuesta es la misma en todos estos casos, y no dice cuál fue:

falta el encabezado Authorization, o no trae un token de la API;
el token no existe, venció o fue revocado;
tu usuario ya no está activo.

Reintentar no sirve. Revisa el encabezado y, si está bien, crea un token nuevo. Un 403 o un 404 no son problemas del token: mira Errores.

El token solo abre esta API

Un token de API se acepta bajo /v1/external y en ningún otro lugar: la API que usa el panel lo rechaza. Lo contrario también vale: la sesión del panel no se acepta en /v1/external.

Autenticación

En esta página