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

# Autenticación

> Claves Connect y cómo autenticar peticiones a /connect/v1.

Todas las peticiones a Connect deben incluir tu clave en el header `Authorization` con esquema **Bearer**. La **misma clave** autentica todos los endpoints (payment intents, addresses, balances, payouts, etc.).

El [SDK del navegador](/sdk-reference/index) **no usa claves** — sólo monta UI a partir de un `payment_intent_id` que tu servidor creó previamente.

## Obtener tus claves

1. Accede al [panel de integración](https://connect.zopay.cash/auth) con tu cuenta de organización.
2. En la sección de desarrolladores, genera una clave **sandbox** (`sk_test_...`) para pruebas.
3. Cuando tu organización esté aprobada, genera una clave **live** (`sk_live_...`) para producción.

Guarda cada clave en un gestor de secretos. **Solo se muestra una vez** al crearla.

## Formato de las claves

| Tipo       | Prefijo    | Uso                                                         |
| ---------- | ---------- | ----------------------------------------------------------- |
| Sandbox    | `sk_test_` | Aislamiento de datos sandbox + acceso a helpers `/test/...` |
| Producción | `sk_live_` | Datos de producción                                         |

<Warning>
  Sandbox y producción operan sobre **redes reales con dinero real**. El prefijo controla el aislamiento de datos y el modo de los webhooks, no si la red es "fake". Ver [Entornos](/get-started/environments).
</Warning>

## Ejemplo de petición

```bash theme={null}
curl -X GET "https://api.zopay.cash/connect/v1/balances" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## Cuenta aprobada

Los endpoints que implican movimiento de fondos exigen que tu organización esté **activa** en Connect. Si aún está en `pending_verification` o `suspended`, recibirás HTTP 403 con código `account_pending_approval`.

## Errores de autenticación

| Situación                                     | HTTP | Código                                             |
| --------------------------------------------- | ---- | -------------------------------------------------- |
| Sin header o formato incorrecto               | 401  | `authentication_required`                          |
| Clave inválida o revocada                     | 401  | `authentication_required`                          |
| Clave con `expires_at` en el pasado           | 401  | `expired_credential`                               |
| Organización no aprobada                      | 403  | `account_pending_approval`                         |
| Clave válida pero sin el scope requerido      | 403  | `forbidden_scope`                                  |
| Clave `sk_live_…` contra una ruta `/test/...` | 404  | (los helpers sandbox son invisibles a claves live) |

El `code` es estable; haz match contra él en tu cliente en lugar de parsear `message`. La diferencia entre `authentication_required` y `expired_credential` es deliberada: la primera dice "revisa el header", la segunda dice "rota la clave".

## Expiración y rotación de claves

Cada clave puede llevar un timestamp opcional `expires_at` (ISO 8601). Cuando se cumple, la API devuelve `401 expired_credential` con un mensaje indicando la fecha. Cuando `expires_at` es `null` (default para claves legacy o minteadas sin TTL), la clave no expira.

### Detectar expiración desde tu cliente

[`GET /connect/v1/health`](/api-reference/endpoints/get-health) devuelve `key_expires_at`:

```bash theme={null}
curl -sS "https://api.zopay.cash/connect/v1/health" \
  -H "Authorization: Bearer $TOKEN" | jq .key_expires_at
# -> "2026-09-01T00:00:00Z"  (o null si no hay expiración)
```

Patrón recomendado: tu servicio chequea `key_expires_at` al arranque y alerta a ops si está dentro de tu ventana de rotación (p. ej. 14 días).

### Envelope del error de expiración

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "expired_credential",
    "message": "This API key expired at 2026-06-02T12:00:00+00:00. Mint a fresh key from the admin panel and update your client.",
    "doc_url": "https://docs.zopay.cash/errors/expired_credential"
  }
}
```

No compartas claves en repositorios públicos, logs ni capturas de pantalla. Rota la clave desde el panel si sospechas una filtración — la rotación invalida la anterior inmediatamente.