> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación

> Cómo funcionan las claves de API, los tokens de acceso de usuario y los alcances (scopes) — para tu propia cuenta y para cuentas de clientes conectadas.

Cada solicitud a la API de Fluz incluye un **token de acceso de usuario** en el encabezado `Authorization`. Cómo obtienes ese token depende de en qué cuenta estás operando.

## Dos caminos, una API

<Columns cols={2}>
  <Card title="Tu propia cuenta" icon="user">
    `API key` → `Tu token`

    Tu servidor intercambia su clave de API de la aplicación por un token con alcance a tu cuenta de Fluz.
  </Card>

  <Card title="La cuenta de un cliente" icon="users">
    `OAuth grant` → `Su token`

    Un cliente autoriza tu app, y Fluz devuelve un token con alcance a su cuenta.
  </Card>
</Columns>

Una vez que tienes un token, el resto de la API es idéntico. `createVirtualCard` con tu token crea una tarjeta en tu billetera; `createVirtualCard` con el token de un cliente la crea en la de ellos.

## Camino 1 — tu propia cuenta

1. En el panel, crea una aplicación y copia su `clientId` y `clientSecret`.
2. Desde tu backend, llama a `generateUserAccessToken` en `https://oauth-service.fluzapp.com/graphql` con tu `clientId`, `clientSecret` y los alcances (scopes) que necesitas.
3. Adjunta el `accessToken` devuelto como `Authorization: Bearer <token>` en cada solicitud al grafo transaccional.

Consulta [Credenciales de API](/get-started/api-credentials) para ver un ejemplo completo.

## Camino 2 — la cuenta de un cliente

Usa esto cuando estés creando una plataforma — por ejemplo, emitiendo tarjetas en nombre de tus usuarios.

1. Redirige al cliente a la URL de autorización de OAuth de Fluz con tu `clientId`, los alcances solicitados y el `redirect_uri`.
2. El cliente inicia sesión y otorga tus alcances.
3. Fluz redirige de vuelta con un `code` de autorización de corta duración.
4. Tu servidor intercambia el código por un token de acceso con alcance al cliente llamando a `generateUserAccessToken` con el código y las credenciales de tu aplicación.
5. Refresca los tokens con alcance al cliente antes de que expiren sin volver a solicitar autorización al cliente.

Recorrido completo en [Crea una plataforma](/build-a-platform).

## Alcances (scopes)

Los tokens incluyen un conjunto explícito de alcances. Algunos comunes por capacidad:

| Área                        | Scopes                                                                                                      |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Tarjetas de regalo          | `LIST_OFFERS`, `PURCHASE_GIFTCARD`, `REVEAL_GIFTCARD`, `LIST_PURCHASES`                                     |
| Tarjetas virtuales          | `CREATE_VIRTUALCARD`, `REVEAL_VIRTUALCARD`, `EDIT_VIRTUALCARD`, `PCI_COMPLIANCE`, `CREATE_SHARE_LINK`       |
| Billeteras y transferencias | `MAKE_DEPOSIT`, `MAKE_WITHDRAWAL`, `MAKE_INTERNAL_TRANSFER`, `MAKE_PAYOUT_TRANSFER_SEND`, `QUERY_RECIPIENT` |
| Fuentes de fondos           | `LIST_PAYMENT`, `MANAGE_PAYMENT`                                                                            |
| Usuarios autorizados        | `MANAGE_SUBUSERS`, `VIEW_SUBUSERS`                                                                          |
| Aprobaciones                | `LIST_APPROVALS`, `MANAGE_APPROVALS`                                                                        |
| Verificación                | `VERIFY_KYC`, `REGISTER_BUSINESS`                                                                           |

Solicita lo mínimo necesario. Cada alcance también tiene una variante `REQUEST_*` usada con el flujo de aprobaciones — consulta [Aprobaciones y Solicitudes](/features/approvals-and-requests). Genera un nuevo token cuando necesites un acceso más amplio.

## Vida útil del token

* **Tokens de acceso:** de corta duración. Refresca antes de que `expiresIn` expire.
* **Tokens OAuth de cliente:** se pueden refrescar a través del servicio de OAuth.
* **`clientSecret` de la aplicación:** válido hasta que se rote en el panel.

<Warning>
  Nunca envíes un `clientSecret` a un navegador o cliente móvil. Emite tokens para tu cuenta; filtrar uno equivale a filtrar tus credenciales.
</Warning>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Obtén tus credenciales de API" icon="key" href="/get-started/api-credentials">
    Camino 1 en la práctica — genera un token para tu propia cuenta y realiza una llamada.
  </Card>

  <Card title="Crea una plataforma" icon="users" href="/build-a-platform">
    Camino 2 en la práctica — conecta cuentas de clientes con el flujo de concesión de OAuth.
  </Card>
</CardGroup>