API essentials
Base reference for hosts, authentication, scope, and public errors.
reference • updated 2026-03-17
HTTP conventions
| Topic | Rule |
|---|---|
| Base host | https://app.beacon.pt/api (live) and https://test.beacon.pt/api (test) |
| Auth | Authorization: Bearer <beacon_session_token> |
| Organization scope | org=<organization_slug> on organization-scoped routes |
| Mode | `mode=test |
| Content-Type | application/json on JSON routes |
| Stripe webhooks | Stripe-Signature is required on /api/webhooks/stripe* routes |
Error payload shape
Errors should return a consistent payload with:
ok: false: explicit failure flag.error: human-readable troubleshooting summary.code: stable category identifier.nextAction: remediation hint when the domain provides one.fieldErrors: optional per-field validation details.
Common status codes
| Code | Meaning | Recommended action |
|---|---|---|
400 | invalid payload or query | fix org, mode, or request body and retry |
401 | missing or invalid bearer token | renew the Beacon session and retry |
403 | caller is not eligible for the action | review OWNER/ADMIN membership in the organization |
409 | current domain state blocks the action | inspect pending checkout, active subscription, or operational blocker |
422 | domain-level semantic validation failed | correct the business input before retrying |