Authentication and idempotency

Authentication contract, scopes, and exactly-once guarantees in Beacon APIs.

reference • updated 2026-03-15

Base headers

Header	Required	Description
`Authorization: Bearer <access_token>`	Yes	Access token scoped to organization context
`Content-Type: application/json`	Yes (POST/PATCH)	Payload format
`Idempotency-Key`	Recommended	Deduplication key for mutable operations

Idempotency rules

Same Idempotency-Key + same endpoint + same organization must produce the same logical outcome.
Use different keys for distinct operations, even with similar payloads.
Persist keys for a defined time window in your operations policy.

Common errors

Code	Meaning	Action
`401`	invalid or missing token	refresh credentials and retry
`403`	insufficient scope	review organization permissions
`409`	idempotent conflict	verify if operation already completed
`429`	throttling	apply retry with backoff

Safe request example

bash

curl -X POST https://api.beacon.pt/v1/billing/subscription-checkouts \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: org-acme-20260315-0001" \
  -d '{"plan":"plus","billing":"monthly"}'