## How to use this reference

This reference is organized by domain and documents the current routes exactly as implemented in the repository.

## Endpoint groups

- [Billing API](/docs/api/billing): subscriptions, checkout, and customer portal.
- [Stripe & Beacon Connect API](/docs/api/stripe-connect): read-only OAuth for existing Stripe and direct platform push.
- [Webhooks API](/docs/api/webhooks): Stripe intake, `event.id` deduplication, and manual replay by `webhookEventId`.
- [Fiscal API](/docs/api/fiscal): documents, reconciliation, and setup state.

## Global conventions

| Topic | Rule |
| --- | --- |
| Base host | `https://app.beacon.pt/api` in `live` and `https://test.beacon.pt/api` in `test` |
| Authentication | `Authorization: Bearer <beacon_session_token>` on authenticated JSON routes |
| Context | `org=<organization_slug>` on organization-scoped routes |
| Mode | `mode=test|live`, constrained by the request hostname |
| Errors | Payload includes `ok`, `error`, `code`, and optionally `nextAction` and `fieldErrors` |

## OpenAPI

Use [OpenAPI spec](/docs/api/openapi-spec) for the partial contract currently modeled in YAML. The spec follows `/api/...`; operational details not yet modeled there are documented in the MDX pages in this section.

<Warning title="Security">These routes depend on Beacon session auth and, in practice, `OWNER` or `ADMIN` membership. Never publish real tokens or use `mode=live` outside the production host.</Warning>