Autenticación e idempotencia

Modelo real de autenticación y deduplicación en las rutas Beacon.

reference • updated 2026-03-17

Headers base

Header	Obligatorio	Descripción
`Authorization: Bearer <beacon_session_token>`	Sí en rutas autenticadas	Token de sesión Beacon resuelto a un usuario local
`Content-Type: application/json`	Sí (POST/PATCH)	Formato del payload
`Stripe-Signature`	Sí en `/api/webhooks/stripe*`	Firma Stripe validada contra el secreto del entorno

Autenticación real

El bearer token se valida contra la sesión Supabase/Beacon y se resuelve a un usuario local.
Las rutas documentadas aquí requieren contexto de organización (org) y, en la práctica, membresía OWNER o ADMIN.
mode=test|live se valida contra el hostname de la petición. test.beacon.pt rechaza live y app.beacon.pt rechaza test.

Deduplicación real

No existe un header público genérico Idempotency-Key en las rutas actuales de Beacon.
POST /api/billing/subscription/checkout genera la clave de idempotencia Stripe en servidor y puede reutilizar un checkout pendiente para la misma operación lógica.
POST /api/webhooks/stripe deduplica por event.id; los duplicados devuelven duplicate: true.
Las rutas de replay o conciliación devuelven queueJobId y pueden reutilizar trabajo ya en curso.

Errores típicos

Código	Significado	Acción
`401`	token inválido o ausente	renovar credenciales y reintentar
`403`	el usuario no es elegible	revisar permisos de organización
`409`	ya existe un estado pendiente o conflicto de dominio	inspeccionar el estado actual antes de forzar una nueva acción
`422`	validación de dominio fallida	corregir el payload funcional y reintentar

Ejemplo de petición segura

bash

curl -X POST "https://test.beacon.pt/api/billing/subscription/checkout?org=acme&mode=test" \
  -H "Authorization: Bearer <beacon_session_token>" \
  -H "Content-Type: application/json" \
  -d '{"plan":"plus","billingCycle":"monthly"}'