Authentication and idempotency

Real authentication and deduplication model for Beacon routes.

reference • updated 2026-03-17

Base headers

Header	Required	Description
`Authorization: Bearer <beacon_session_token>`	Yes on authenticated routes	Beacon session token resolved to a local user
`Content-Type: application/json`	Yes (POST/PATCH)	Payload format
`Stripe-Signature`	Yes on `/api/webhooks/stripe*`	Stripe signature validated against the environment secret

Real authentication

The bearer token is validated against the Supabase/Beacon session and resolved to a local user.
The routes documented here require organization context (org) and, in practice, OWNER or ADMIN membership.
mode=test|live is validated against the request hostname. test.beacon.pt rejects live and app.beacon.pt rejects test.

Real deduplication

There is no generic public Idempotency-Key header on the current Beacon routes.
POST /api/billing/subscription/checkout generates the Stripe idempotency key server-side and can reuse a pending checkout for the same logical request.
POST /api/webhooks/stripe deduplicates by event.id; duplicates return duplicate: true.
Replay and reconciliation-style routes return queueJobId and may reuse work that is already in progress.

Common errors

Code	Meaning	Action
`401`	invalid or missing token	refresh credentials and retry
`403`	caller is not eligible	review organization permissions
`409`	pending state or domain conflict already exists	inspect current state before forcing a new action
`422`	domain validation failed	fix the business payload and retry

Safe request example

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"}'