Auth Flow

Schedule-X Cloud uses two credentials in customer integrations: an organization API token for your backend and a frontend token for browser sessions.

Credential	Audience	Used for	Browser safe
Organization API token	Your backend	Creating frontend sessions and managing organization resources	No
Frontend token	Browser session for one organization user	Loading Schedule-X config and persisting events	Yes, short-lived

Get Access

Get an organization API token by emailing tom@schedule-x.dev.

Store the values as backend environment variables:

SCHEDULE_X_ORGANIZATION_ID=<organization-id>
SCHEDULE_X_ORG_API_TOKEN=sx_org_...

The organization API token can create users, create calendars, list organization resources, and issue frontend tokens. Treat it like a password.

User Authentication Model

Schedule-X Cloud does not replace your app login. Your application authenticates users first, then your backend maps that app user to a Schedule-X Cloud user.

The recommended flow is:

1. User signs in to your application.
2. Your backend calls createFrontendSession() with its stable external user ID and profile.
3. Schedule-X finds or creates the Cloud user and returns a one-hour frontend token.
4. Your browser passes an async getFrontendToken() function to createScheduleXCloudCalendar().

Creating or updating the Cloud user and issuing its token:

POST /v1/orgs/{organizationId}/auth/frontend-session
X-ScheduleX-Api-Key: sx_org_...
Content-Type: application/json

{
  "externalUserId": "app-user-123",
  "email": "ada@example.com",
  "displayName": "Ada Lovelace"
}

The external user ID is organization-scoped and immutable. The first call creates a Member; subsequent calls update email/display name without changing the role. The low-level user and frontend-token endpoints remain available for advanced workflows.

Frontend Token Exchange

Response:

{
  "token": "sx_front_...",
  "organizationId": "...",
  "userId": "...",
  "expiresAt": "2026-06-03T12:00:00Z"
}

Browser requests send the token as a bearer token:

GET /v1/schedule-x/config
Authorization: Bearer sx_front_...

The API resolves the organization and user from the token, so browser code does not need to send an organization id for default config and event routes.

Permission Model

• A valid organization API token can access server-side organization routes for its own organization and key-bound environment.
• A valid organization API token can only issue frontend tokens for users in its own organization.
• A valid frontend token can load its permission-shaped Schedule-X config through browser routes.
• Frontend tokens cannot access any /v1/orgs/** route, including same-organization users, memberships, subscription data, raw calendars, raw events, or config.
• Browser event writes require the token user to have Owner, Admin, or Member membership in the organization.
• Viewer users can be represented in memberships, but event write access is rejected.
• Frontend tokens expire according to SCHEDULEX_FRONTEND_TOKEN_TTL_MINUTES.
• Named organization API tokens can expire or be revoked.

Token Handling Rules

• Keep SCHEDULE_X_ORG_API_TOKEN on the server.
• Do not store frontend tokens in long-lived browser storage unless your app has a specific reason.
• Reissue frontend tokens from your backend when they expire.
• Use HTTPS in production.
• If an organization API token is exposed, revoke it and request or create a replacement.