# Autenticación

Cómo autenticarte en la API de vexorpay con tu clave.

> [!WARNING]
> El SDK `vexor` de npm (Stripe, MercadoPago, PayPal, Square, Talo) está **deprecado**: ya no se mantiene y no debe usarse. vexorpay es hoy una **API REST de links de pago en USD sobre Polar (Merchant of Record), sin SDK oficial**. Migración: <https://developers.vexorpay.com/docs/migracion-desde-el-sdk>

Fuente: <https://developers.whop.vexorpay.com/docs/api/authentication>

Cada request a la API de vexorpay debe incluir tu **API key** en el header `Authorization`.

## Header

```
Authorization: Bearer vxp_live_tu_clave
```

## Formato de la clave

La clave lleva el **modo** en su propio formato:

| Formato | Modo |
| --- | --- |
| `vxp_live_<shard>_<entropy>` | **Producción** |
| `vxp_test_<shard>_<entropy>` | Pruebas (**sandbox**) |

`<shard>` son 10 caracteres hex que identifican al usuario. La clave se muestra **una sola vez** al crearla: si la pierdes, tienes que revocarla y crear una nueva.

> **Compatibilidad.** Las claves creadas con los formatos anteriores (`vxp_u_<shard>_...` y el viejo `vxp_live_...`) siguen funcionando y son de **producción**.

## El modo lo define la clave, no el request

No existe un parámetro `sandbox` en los requests: ni en el body de los `POST` ni en el query string de los `GET`. El modo sale de la clave:
con `vxp_test_...` se opera sobre datos de prueba; con `vxp_live_...`, sobre datos de producción.

Cada host de API solo acepta claves de su modo:

| Host | Acepta |
| --- | --- |
| `https://api.vexorpay.com` | Solo claves `vxp_live_...` |
| `https://api.sandbox.vexorpay.com` | Solo claves `vxp_test_...` |

Si la clave no coincide con el host, la API responde `403 livemode_mismatch`. Ver [Modo sandbox](/docs/sandbox-mode) para saber cómo se eligen las claves de prueba.

Los tokens OAuth (`vxo_at_...`) no pasan por el gate de host: el modo queda fijado por la conexión.

## Obtén tu clave

Una API key se crea desde **Desarrolladores** en el dashboard (dentro de una aplicación, con «Nueva API key»): desde el dashboard de producción se crean claves live (`vxp_live_...`) y desde `dashboard.sandbox.vexorpay.com` se crean claves de prueba (`vxp_test_...`). Cada modo tiene su propio límite de **20 claves**.

## Rate limit

El límite es de **100 requests por minuto** por clave. Las respuestas llevan los headers:

- `X-RateLimit-Limit` — límite de la ventana.
- `X-RateLimit-Remaining` — requests restantes.
- `X-RateLimit-Reset` — timestamp (epoch) en que se reinicia la ventana.

Al superarlo, la API responde `429` con `Retry-After` (segundos). Si tu integración necesita más, escríbenos para subir el cupo.

Los headers viajan en **todas** las respuestas, incluidos los `401`. Los requests sin una clave válida
(sin `Authorization`, o con una clave inexistente o revocada) se limitan aparte con el mismo tope de
100/min: se identifican por el hash de la clave presentada, o por tu IP si no mandás `Authorization`,
así que tampoco se puede probar claves al límite.

## Errores de autenticación

| Error | Descripción |
| --- | --- |
| `unauthorized` | Falta el header `Authorization`. |
| `invalid_key` | La clave es inválida o fue revocada. |
| `livemode_mismatch` | La clave y el host no coinciden en modo: la clave es de prueba y se usó en el host de producción (o al revés). Ver [Modo sandbox](/docs/sandbox-mode). |

## Seguridad

- Nunca compartas tu clave en repositorios públicos o código expuesto al navegador.
- Si una clave se ve comprometida, revócala de inmediato desde el dashboard y crea una nueva.

## Base URL

```
https://api.vexorpay.com/api/v1
```