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

# API keys

> Autentica tus integraciones server-to-server con una API key bxm_ de Finzaria.

Toda llamada a la API lleva el header:

```
Authorization: Bearer <token>
```

Donde `<token>` puede ser una **API key `bxm_`** (esta página) o un
[access token de OAuth](/guias/autenticacion/oauth). Usa una **API key** cuando tú (o tu backend)
accedes a **tu propia cuenta**. Usa **OAuth** cuando tu app o un agente actúa **a nombre de otro usuario**.

## Crear una API key

<Steps>
  <Step title="Abre Developers en la app">
    [app.finzaria.com](https://app.finzaria.com) → perfil → **Developers**.
  </Step>

  <Step title="Crea la key y copia el valor">
    Elige un **nombre** (p. ej. "Backend producción") y un **scope**
    ([`read_only` o `read_write`](/guias/autenticacion/scopes)). El valor completo (`bxm_…`) se
    muestra **una sola vez** — cópialo de inmediato.
  </Step>
</Steps>

<Warning>
  La API key da acceso a tu cuenta. **Nunca** la subas a git, la incrustes en una app de navegador o
  móvil, ni la compartas. Guárdala en un gestor de secretos (variables de entorno, Vault, etc.).
</Warning>

## Usarla

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.finzaria.com/v1/accounts \
    -H "Authorization: Bearer $FINZARIA_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://api.finzaria.com/v1/accounts", {
    headers: { Authorization: `Bearer ${process.env.FINZARIA_API_KEY}` },
  })
  ```

  ```python Python theme={null}
  import os, requests
  requests.get(
      "https://api.finzaria.com/v1/accounts",
      headers={"Authorization": f"Bearer {os.environ['FINZARIA_API_KEY']}"},
  )
  ```
</CodeGroup>

Sin token, o con uno inválido/revocado, la API responde `401` con
[`problem+json`](/guias/referencia-transversal/errores):

```json theme={null}
{
  "type": "https://finzaria.com/problems/auth-invalid-token",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key inválida o revocada",
  "code": "AUTH_INVALID_TOKEN"
}
```

## Rotación sin downtime

Las keys no expiran solas; rótalas periódicamente. Para no cortar el servicio:

<Steps>
  <Step title="Crea una key nueva">Genera una segunda key con el mismo scope.</Step>
  <Step title="Despliega la nueva">Actualiza tu secreto/entorno para usarla.</Step>
  <Step title="Revoca la vieja">Elimínala en **Developers**. La revocación es **inmediata** (el siguiente request con esa key da `401`).</Step>
</Steps>

## Buenas prácticas

* **Una key por uso** (backend, script, integración) — así revocas una sin afectar las demás.
* **Mínimo privilegio**: si solo lees, usa `read_only`.
* **Rota** en un calendario y ante cualquier sospecha de fuga.
* Nunca la pongas en el frontend; ahí va [OAuth](/guias/autenticacion/oauth).