Platform Auth and Scopes

Use this page when the main question is about who can connect, how credentials are issued, and what an integration is allowed to do.

The three auth contexts

SyncReserve uses different auth models for different jobs.

Public access

No tenant credential is required for public discovery surfaces such as llms.txt and public search-oriented routes.

Use this mode only for public browsing and discovery.

Tenant-admin setup access

Some routes are setup surfaces for club operators rather than runtime integration calls.

These routes depend on a tenant admin session because the club is approving, registering, or managing access.

The main operator-facing setup surface is Settings > Developers, where owners and managers can create apps, issue keys, manage webhooks, and hand customer developers into /docs.

Runtime platform access

Runtime platform calls use either:

platform API keys
OAuth 2.1 authorization code with PKCE

This is the model used for the authenticated external contract, including MCP.

App registration and key management

Before most private integrations run, a tenant sets up an app record and then issues one or more credentials.

Apps

The platform app surface is the registration layer for tenant-installed integrations.

An app record defines the external application identity and allowed origins. That keeps setup separate from day-to-day API traffic.

API keys

The key-management surface is where a club issues and governs platform credentials.

Keys can vary by:

mode: live or test
type: secret or restricted
scopes: broad or narrow capability access

For public docs, the important point is that clubs can issue narrower credentials instead of handing every integration a full-power secret.

Plaintext secrets are one-time reveal only in the admin workspace. If an operator loses a key or webhook signing secret, they must rotate or recreate it rather than retrieve the old plaintext value.

OAuth

OAuth is the right fit when an external application needs a tenant-approved installation flow rather than manually created keys.

Main routes:

GET /api/v1/platform/oauth/authorize
POST /api/v1/platform/oauth/token

Publicly, this matters because it signals that SyncReserve can support installable app patterns, not only key-based server-to-server access.

Scope vocabulary

Current public scope vocabulary includes:

tenant:profile:read
analytics:read
bookings:discovery:read
export:read
events:read
webhooks:manage
bookings:write
checkins:write

How to choose a credential model

Use the smallest model that fits the job.

Use public discovery when no private tenant data is needed.
Use a restricted API key for server-to-server reads or tightly scoped automation.
Use OAuth when the integration should be installed and approved by tenant admins.
Use broader write access only when the integration genuinely needs operational actions.

Test mode and live mode

SyncReserve separates test and live access.

That matters for:

safe integration development
webhook delivery targeting
premium write validation
launch readiness before production use

Public docs should make that separation visible, but they should not disclose internal rollout or environment wiring details.

Security expectations

The platform model is designed around tenant-scoped least privilege.

That means:

credentials should hold only the scopes they need
write-capable integrations should use safer retry and idempotent patterns
test credentials should not be treated as live production access
admin browser login and platform credentials are different trust models

What this page is not

This page describes the public auth model.

It is not:

a secret-management runbook
a full OAuth implementation tutorial
a replacement for endpoint-specific contract docs

/docs/reference/developers-workspace
/docs/platform-api/platform-api-overview
/docs/platform-api/webhooks-and-event-delivery
/docs/platform-api/mcp-tools-and-agent-workflows