Autenticación

La API programática de Rekurra (todo bajo /v1/*) se autentica exclusivamente con API keys. No existen sesiones ni cookies en esta capa — eso es exclusivo del dashboard (/dashboard/*, autenticado por email/password u OAuth) y del panel de administración (/admin/*).

Formato de las llaves

rk_live_XXXXXXXXXXXXXXXXXXXXXXXX   # producción — cobra sobre dinero real
rk_test_XXXXXXXXXXXXXXXXXXXXXXXX   # pruebas — usa el sandbox de Wompi

Cada llave pertenece a un solo desarrollador (tenant). Todos los recursos que crees o consultes (planes, clientes, suscripciones, etc.) quedan aislados a ese tenant — nunca verás datos de otro desarrollador.

Cómo autenticar una request

Envía la llave en el header Authorization como un Bearer token:

curl

curl https://api.rekurra.dev/v1/plans \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"

JavaScript (fetch)

const res = await fetch("https://api.rekurra.dev/v1/plans", {
  headers: {
    Authorization: "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX",
  },
});
const data = await res.json();

Python (requests)

import requests
 
res = requests.get(
    "https://api.rekurra.dev/v1/plans",
    headers={"Authorization": "Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXX"},
)
data = res.json()

Generar una API key

Entra al dashboard de Rekurra → Configuración → API keys.
Haz clic en Crear API key, elige el modo (live o test) y los scopes que necesitas.
Copia la llave completa — se muestra una sola vez. Rekurra solo almacena un hash SHA-256 de la llave más los últimos 4 caracteres para mostrarla en el dashboard (rk_live_••••••••••••••••••••ab3f).

⚠️

Si pierdes una API key no hay forma de recuperarla: debes revocarla y generar una nueva. Nunca la compartas ni la incluyas en código del lado del cliente (frontend).

Scopes

Cada llave puede limitarse a un conjunto de scopes (por ejemplo, plans:read, subscriptions:write, charges:read). Una request que use un scope no autorizado por la llave recibe 403 Forbidden.

Revocación

Puedes revocar una llave en cualquier momento desde el dashboard. Una vez revocada, cualquier request que la use responde 401 Unauthorized inmediatamente — no hay periodo de gracia.

Live vs. test

	`rk_live_...`	`rk_test_...`
Cobra dinero real	Sí	No
Wompi	Producción (Merchant real)	Sandbox de Wompi
Datos	Aislados de test	Aislados de live
Webhooks	Se disparan igual	Se disparan igual

Errores de autenticación

Status	Causa
`401`	Llave faltante, inválida o revocada
`403`	La llave no tiene el scope necesario para la operación

401 — llave inválida

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La API key proporcionada no es válida o fue revocada.",
    "request_id": "req_01HZX..."
  }
}

Ver Errores para el detalle completo del objeto de error.

Introducción Plan