Programmatic API Catalog and Token Scopes
How to use personal access tokens, scope groups, and the live API catalog when automating GetPaidX from scripts or workspace agents.
Programmatic API Catalog and Token Scopes
Where you see this in the app
The browser setup surface is Settings -> API.
That page lets signed-in users create personal access tokens, choose scopes, add webhook endpoints, and delete old entries. The live machine-readable API reference is available from /api/programmatic/catalog.
Personal access token basics
A personal access token is an account-approved key for calling GetPaidX APIs from scripts, workspaces, or other automation clients.
Use a PAT when:
- your own script needs to create or read posts,
- a workspace agent needs to call GetPaidX on your behalf,
- you want to manage webhooks or automation settings without clicking through the browser UI.
Keep the token value private. The settings page shows the raw value only when the token is first created.
Scope groups
Token scopes are grouped by capability.
| Group | Common scopes |
|---|---|
| Content | posts:read, posts:write, places:read, artifacts:write |
| Workspace | workspaces:run, workspaces:manage |
| Billing | billing:read, billing:checkout, billing:manage, payouts:manage, transfers:manage |
| Account | notifications:read, notifications:write, memberships:manage, sharing:manage, webhooks:manage |
| Live Sessions | live_sessions:read, live_sessions:write, live_sessions:join, live_sessions:moderate, gated live_sessions:commerce |
Choose the smallest set that matches the job. For example, a script that only reads notification settings should not need post-writing or payout-management scopes.
Live API catalog
Agents and scripts should call /api/programmatic/catalog before assuming which endpoints support PAT auth.
The catalog describes:
- supported scopes,
- endpoint method and path,
- whether PAT auth is supported,
- browser-session support,
- request and response hints,
- common errors,
- workflow guidance.
The catalog is the best current source of truth for automation clients because it reflects the live route contract better than a copied static list.
Browser session vs bearer token
Some routes support both browser sessions and PAT bearer tokens. Other routes are browser-only, public, webhook-ingress, internal, or admin-only.
For PAT calls, send:
Authorization: Bearer gpx_pat_...
When a PAT lacks the required scope, the route should reject the request before doing the protected work. Some billing and Stripe routes can now create hosted redirect URLs for scoped PAT callers, but completing external Stripe flows still happens in Stripe-hosted browser pages.
Common scope examples
| Job | Likely scope |
|---|---|
| Read feed or post data | posts:read |
| Create or update posts | posts:write |
| Start workspace sessions or manage bindings | workspaces:manage |
| Queue or inspect automation runs | workspaces:run |
| Create checkout links | billing:checkout |
| Start Stripe Connect onboarding | payouts:manage |
| Manage referral paths or AI QR generations | sharing:manage |
| Read or update notification settings | notifications:read / notifications:write |
| Read/configure/schedule a Live Session | live_sessions:read / live_sessions:write |
| Join or moderate a Live Session | live_sessions:join / live_sessions:moderate |
If a call fails with a missing-scope response, create a new token with the needed scope instead of reusing a broader token everywhere.
Live Sessions control plane
Live Sessions are optional post features controlled by deployment settings. The catalog workflow live_session_setup covers room configuration, a Presentation or Conversation format, and Now/Schedule occurrence creation. Starting or joining fails closed when the selected RTC provider is unavailable; this does not interrupt the underlying post, workspace, place, or payment surfaces. Live offers have their own enablement setting.
Read GET /api/posts/{postId}/extensions/live-sessions/summary for visible sessions, the caller's join/access actions, and session/conversation links. Signed-out callers receive a minimal summary of visible posts; explicit tokens must still be valid and carry the required scope. The summary excludes provider references, participant rosters and conversation bodies.
Use a stable idempotencyKey when creating a session so a retry recovers the same attempt. Set metadata.interactionMode to PRESENTATION for a listening audience or DISCUSSION for attendee microphone/camera permission; Conversation does not grant presenter, screen-sharing or management rights. Capacity is bounded by the deployment. A purchase or eligible subscription can cover sessions on the parent post; it is not a reservation for one date.
Conversation reads support the original forward cursor, or latest=true for a recent chronological window followed by before to load earlier history. In MCP/WebMCP, getpaidx_get_live_room accepts summary=true and optional sessionId; getpaidx_create_live_session accepts idempotencyKey; getpaidx_list_live_session_messages accepts latest and before. The curated session UI-link tool returns an occurrence-specific link without credentials. Cataloged APIs retain their normal scoped authentication and authorization.
Use PATCH /api/live-sessions/{sessionId} to reschedule an occurrence that is still SCHEDULED, and POST /api/live-sessions/{sessionId}/cancel to cancel it. Both require live_sessions:write; cancellation is idempotent after cancellation and rejects a concurrent start. In MCP/WebMCP, getpaidx_end_live_session accepts cancelScheduled=true for that operation. Canceling does not refund payments or revoke post-wide access. End can be retried while ENDING after a temporary provider failure.
Participant role PATCH and removal DELETE require live_sessions:moderate. A role can be saved before media entry. The returned participant’s capabilities.providerSync reports ON_NEXT_JOIN, APPLIED or PENDING; a retryable provider error can leave the product change saved with media synchronization pending. To retry a role safely, send expectedRevision equal to its current providerSync.requestId; a newer command returns 409 instead of being overwritten. The curated getpaidx_update_live_session_participant tool accepts the same optional field. Removal is idempotent and denies fresh application admission immediately. Cached self-hosted media credentials are handled by current-policy join enforcement and provider token limits; application removal does not promise instantaneous cryptographic token revocation.
Join credentials are short-lived secrets. The server derives the caller identity, participant role, provider room, admission decision, capacity, and media capabilities. Clients must not send or trust their own userId, host role, or room name.
Optional offers can be enabled with room metadata.offersEnabled=true independently of the session format. An explicit false disables that capability, including on a legacy LIVE_COMMERCE room. The independent commerce deployment gate and double-blind restrictions still apply.
Read GET /api/checkout/quote?postId=... with billing:checkout for a buyer-specific effective quote and existing post access. A visible signed-out post has an anonymous quote, while invalid/underscoped explicit tokens remain rejected. Passing the quote's id as quoteId to POST /api/checkout prevents price/economics changes from silently creating a payment. Admitted live-offer reads also include the quote, current purchase state and permitted delivery links, including retained outcomes after ending. MCP/WebMCP can use the cataloged quote endpoint through getpaidx_api_call and the enriched getpaidx_list_live_offers; catalog discovery also needs posts:read.
Send a stable idempotencyKey with POST /api/checkout. The server stores the accepted financial/account context before contacting Stripe and reuses an existing active product checkout for that buyer. Read GET /api/checkout/attempts (optional postId, liveSessionId, or bounded comma-separated postIds) or GET /api/checkout/attempts/{attemptId} for caller-owned status. Explicit POST .../{attemptId}/resume recovers that open checkout; POST .../{attemptId}/expire confirms provider expiry before a fresh request. These routes use billing:checkout; browser mutations require the exact same origin. Read projections exclude the client secret, while an authorized open resume can return the existing embedded secret or hosted URL. A completed form can still be processing; access follows authoritative purchase/membership state.
Related docs
Related docs
See it in action
Previous
Android App and Device Notifications
How Android app mode, the feed push prompt, and device-level notification subscriptions work for signed-in users.
Next
Organizations, Billing Groups, and Pro Seats
How organization rosters, roles, invitations, shared AI-credit wallets, org-billed usage, Pro seat subscriptions, and seat assignments work.