# Autenticación
URL: https://docs.fluenta.io/docs/authentication

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 [#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](/docs/ai).

## Crear un token [#crear-un-token]

1. Entra a `app.fluenta.io` y abre «Configuración» → «Tokens de API».
2. Pulsa «Crear token».
3. Escribe un «Nombre» que te diga dónde lo usas. Admite hasta 64 caracteres.
4. En «Permisos», «Leer» viene siempre. Marca «Gestionar el Programa» solo si
   el programa va a escribir: mira [Permisos](/docs/permissions).
5. Elige el «Vencimiento»: «Nunca», «30 días», «90 días» o «1 año».
6. 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 [#enviar-el-token]

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

## Guardar el token [#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 [#rotar-un-token]

No hay una acción de rotar:

1. Crea un token nuevo con los mismos permisos.
2. Cambia el secreto en tu programa y despliégalo.
3. Mira «Último uso» del token viejo en «Tus tokens» para confirmar que ya
   nadie lo usa.
4. 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 [#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 [#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 [#qué-significa-un-401]

```json
{
  "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](/docs/errors).

## El token solo abre esta API [#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`.