> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Autenticación

> Cómo autenticarte con la API de Recurrente

Todas las solicitudes de API requieren autenticación a través del header HTTP `X-SECRET-KEY`:

| Header         | Descripción                               |
| -------------- | ----------------------------------------- |
| `X-SECRET-KEY` | Tu llave secreta de API                   |
| `X-ACCOUNT-ID` | Opcional. ID de una cuenta hija conectada |

La llave secreta determina la **plataforma** y el **ambiente** (producción o prueba). Sin `X-ACCOUNT-ID`, los requests operan sobre esa misma cuenta.

## Empieza en Sandbox

Para una integración nueva, abre **Configuración → Llaves API → Abrir Sandbox** y elige **Crear mi llave TEST**. Sigue [Primer pago de prueba](/guias-espanol/comenzar/primer-pago-de-prueba). Las llaves TEST solo existen dentro de un Sandbox: tu cuenta de producción tiene únicamente llaves LIVE. `GET /test` devuelve `environment` (`sandbox` o `live`) y `sandbox_id` para confirmarlo. No necesitas llave pública.

## Cuentas personales y comerciales

Las cuentas personales y comerciales pueden generar llaves TEST y LIVE desde **Configuración → Llaves API**. El Sandbox de arriba es para cuentas comerciales; una cuenta personal prueba con su llave TEST. Los administradores de la cuenta pueden gestionar las llaves; este cambio no concede acceso a otros roles del equipo.

Ambos tipos pueden ser la plataforma o una cuenta hija existente. Para conectar una cuenta personal existente, usa el enlace de invitación de la plataforma y selecciona explícitamente la cuenta personal. La plataforma utiliza su propia llave con `X-ACCOUNT-ID`; el destinatario no necesita compartir ni generar una llave.

El acceso a la API no cambia la verificación, los límites de procesamiento, la disponibilidad de cuotas ni los permisos de la llave para mover dinero. Admitir un tipo de cuenta no aprueba automáticamente el caso de uso de una plataforma.

## Contexto de una cuenta conectada

Si la llave pertenece a una plataforma, agrega `X-ACCOUNT-ID` para ejecutar un request dentro de una hija conectada, de la misma forma que `Stripe-Account` en Stripe Connect:

```bash
curl https://app.recurrente.com/api/intents \
  -H "X-SECRET-KEY: sk_live_xyz789..." \
  -H "X-ACCOUNT-ID: ac_hija123"
```

La plataforma puede listar, consultar y administrar los recursos API que pertenecen a esa hija, sin importar si los creó la plataforma o la hija. El contexto cubre, entre otros, checkouts, clientes, productos, suscripciones, intents, payment intents, reembolsos, balances y transferencias.

Solo se aceptan hijas conectadas directamente a la cuenta dueña de la llave. El acceso no es transitivo hacia cuentas conectadas a la hija. Los endpoints bajo `/connected_accounts` siguen siendo operaciones de la plataforma y reciben el ID de la hija en el path. Los endpoints que ya aceptan `account_id` lo conservan como alias compatible. Las capacidades de la llave, la verificación de la cuenta y las restricciones de destinos para mover dinero siguen aplicando dentro del contexto conectado.

## Llaves públicas y privadas

La llave privada (también llamada secreta) se envía en `X-SECRET-KEY`.
Las integraciones anteriores usaban una llave pública en `X-PUBLIC-KEY`; la API
actual ya no usa ese header para autenticar. Conserva la llave privada en tu
servidor, nunca en código del navegador ni en un repositorio público.

## Encontrar Tus Llaves

Para encontrar tus Llaves de API, dentro de tu cuenta de Recurrente, ve a:

**Configuración** → **Llaves API.**

1. Inicia sesión en el [Panel de Recurrente](https://app.recurrente.com)
2. Ve a **Configuración → Llaves API**
3. Copia tu llave secreta. Solo se muestra completa al generarla o rotarla.

## Producción y Sandbox

Cada cuenta tiene un solo ambiente, y todas sus llaves pertenecen a él:

* **Llaves de producción** (`sk_live_`) — Viven en tu cuenta de producción. Se procesan transacciones reales.
* **Llaves de prueba** (`sk_test_`) — Viven solo dentro de un Sandbox. No se mueve dinero real.

El endpoint de la API es el mismo para ambos. La llave secreta determina en qué ambiente estás operando.

Antes, las cuentas de producción también tenían una llave TEST propia. Esas llaves se retiraron: una llave `sk_test_` que ya no existe responde `401` con un mensaje que te lleva al Sandbox. Los objetos de prueba (`live_mode: false`) que crearon siguen en la cuenta, pero una llave de producción nunca los lista ni los resuelve (`404`, o `401` en `/customers`).

## Solicitud de Ejemplo

```bash
curl https://app.recurrente.com/api/test \
  -H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY"
```

## Error en la autenticación

Si tus llaves de API no se están enviando o son inválidas, recibirás un código de respuesta HTTP 401 Unauthorized:

```json
{
  "message": "Autenticación Errónea 👀",
  "errors": {
    "authentication": [
      "Las llaves de API son inválidas o no coinciden."
    ]
  }
}
```

## Ambientes

| Ambiente   | URL Base                                                         |
| ---------- | ---------------------------------------------------------------- |
| Producción | `https://app.recurrente.com/api`                                 |
| Sandbox    | `https://app.recurrente.com/api` (usa la llave TEST del Sandbox) |