# Authentication
URL: https://docs.fluenta.io/en/docs/authentication

The API's two credentials, and how to create, store, rotate and revoke an API token.



Here you will see which credential fits you, how to create, store, rotate and
revoke an API token, and what a 401 means.

## Two credentials [#two-credentials]

Both are sent the same way: `Authorization: Bearer fluenta_live_…`.

|                | API token                                                                  | Connection                                                               |
| -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Who creates it | You, by hand, in «Configuración» (Settings) → «Tokens de API» (API tokens) | An AI app, such as Claude or ChatGPT, when you press «Permitir» (Allow)  |
| What it is for | Your own programs                                                          | Using Fluenta from the AI app, over MCP, at `https://app.fluenta.io/mcp` |
| Plans          | Light and Pro                                                              | Pro: it is the «Conectar con IA» (Connect with AI) feature               |
| How it ends    | It expires, or you press «Revocar» (Revoke)                                | You press «Desconectar» (Disconnect)                                     |

Both act as you: they reach your organizations, with your role. `GET /me` says
which one you presented in `credential.kind`: `personal` is an API token and
`oauth` is a connection.

For a script, a weekly report or a spreadsheet, use an API token. For an AI
app, use a connection: see [AI](/en/docs/ai).

## Create a token [#create-a-token]

1. Sign in at `app.fluenta.io` and open «Configuración» → «Tokens de API».
2. Press «Crear token» (Create token).
3. Type a «Nombre» (name) that tells you where you use it, up to 64
   characters.
4. Under «Permisos» (permissions), «Leer» (Read) is always granted. Tick
   «Gestionar el Programa» (Manage the Programa) only if the program will
   write: see [Permissions](/en/docs/permissions).
5. Pick the «Vencimiento» (expiry): «Nunca» (never), «30 días», «90 días» or
   «1 año».
6. Press «Crear token» and copy the token with «Copiar token» (Copy token).

The token is shown once. Fluenta keeps only its hash and cannot show it
again: if you lose it, create another.

You may hold up to 10 live tokens and create up to 10 an hour.

## Send the token [#send-the-token]

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

## Store the token [#store-the-token]

* Keep it server-side only: in an environment variable or in your platform's
  secret manager.
* Never put it in code that runs in a browser, or in a repository.
* Never put it in a URL: the API reads it from the `Authorization` header
  only.
* Use one token per program, so you revoke one without stopping the others.
* «Tus tokens» (Your tokens) lists the first 16 characters of each: enough to
  tell them apart, not to authenticate.

A token that never expires works until you revoke it. Resetting your password
does not revoke your tokens.

## Rotate a token [#rotate-a-token]

There is no rotate action:

1. Create a new token with the same permissions.
2. Change the secret in your program and deploy it.
3. Check the old token's «Último uso» (last used) in «Tus tokens» to confirm
   nothing uses it.
4. Press «Revocar» on the old token.

A token gains no permission after it is created. If you need «Gestionar el
Programa», create a new one.

## Revoke a token [#revoke-a-token]

Press «Revocar» on the token's row and confirm. It takes effect at once: the
next request with that token answers 401.

## Expiry [#expiry]

`GET /me` answers when the token expires in `credential.expiresAt` (ISO 8601,
UTC; `null` when it never expires). After that date the token answers 401 and
cannot be renewed: create another.

## What a 401 means [#what-a-401-means]

```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."
}
```

The answer is the same in all of these cases, and does not say which:

* the `Authorization` header is missing, or does not carry a token of the API;
* the token does not exist, expired or was revoked;
* your user is no longer active.

Retrying does not help. Check the header and, if it is right, create a new
token. A 403 or a 404 is not about the token: see [Errors](/en/docs/errors).

## The token opens this API only [#the-token-opens-this-api-only]

An API token is accepted under `/v1/external` and nowhere else: the API the
dashboard uses refuses it. And a dashboard session is not accepted under
`/v1/external`.