Beacon

API essentials

View as Markdown

API essentials

Base reference for hosts, authentication, scope, and public errors.

reference • updated 2026-03-17

HTTP conventions

TopicRule
Base hosthttps://app.beacon.pt/api (live) and https://test.beacon.pt/api (test)
AuthAuthorization: Bearer <beacon_session_token>
Organization scopeorg=<organization_slug> on organization-scoped routes
Mode`mode=test
Content-Typeapplication/json on JSON routes
Stripe webhooksStripe-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

CodeMeaningRecommended action
400invalid payload or queryfix org, mode, or request body and retry
401missing or invalid bearer tokenrenew the Beacon session and retry
403caller is not eligible for the actionreview OWNER/ADMIN membership in the organization
409current domain state blocks the actioninspect pending checkout, active subscription, or operational blocker
422domain-level semantic validation failedcorrect the business input before retrying