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

# Authentication

> Cómo autenticar requests con una API key del negocio y qué alcance tiene.

# Authentication

La API se autentica con una **API key del negocio**. Enviá la clave en el header
`Authorization` (recomendado):

```http theme={null}
Authorization: Bearer finup_xxxxxxxxxxxxxxxxxxxxxxxx
```

o con el header alternativo:

```http theme={null}
X-API-Key: finup_xxxxxxxxxxxxxxxxxxxxxxxx
```

La clave se genera y administra desde FinUp (**API Keys**). Ver
[Claves API](/guia/api-keys).

## Alcances

| Alcance | Métodos permitidos |
| - | - |
| **Solo lectura** (`read`) | `GET`, `HEAD`, `OPTIONS` |
| **Acceso total** (`full`) | Todos (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) |

Un request con clave de solo lectura a un método de escritura responde:

```json theme={null}
{ "error": "This API key only allows read access" }
```

con status `403`.

## Qué puede y qué no

* ✅ Operar sobre **tu negocio**: clientes, créditos, cuotas, pagos, sucursales,
  configuraciones, reportes, auditoría y verificación ARCA/BCRA.
* ❌ **Otros negocios** o la consola de superadmin: no existe forma de cambiar de
  negocio con una clave.
* ❌ **Administrar claves** (`/api/api-keys`): esa gestión requiere una sesión de
  **administrador** en la app, no una clave. Con una API key responde
  `403 { "error": "API keys cannot be managed with an API key" }`.
* ❌ Endpoints de **sesión web**: `/api/me` (usuario logueado) y `/api/admin/*`
  (superadmin). Requieren login con cookie; no se pueden usar con una API key.

## Errores de autenticación

| Status | Cuándo |
| - | - |
| `401 Unauthorized` | Falta la clave, es inválida o fue **revocada**. |
| `403 Forbidden` | La clave es de **solo lectura** y el método es de escritura. |

```json theme={null}
{ "error": "Invalid API key" }
```

## Buenas prácticas

* Usá **una clave por integración o entorno** (por ejemplo, una para producción
  y otra para pruebas).
* Guardá la clave en un **gestor de secretos** o variable de entorno. **Nunca**
  la pongas en código de navegador ni en repositorios públicos.
* Preferí una clave de **solo lectura** cuando la integración no necesite
  escribir.
* Si sospechás que se filtró, **revocala** y creá una nueva: la revocación es
  inmediata.