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 extensions and are globally disabled by default while the media provider rollout is in progress. The catalog workflow live_session_setup covers room installation/configuration and provider-independent occurrence scheduling. Starting or joining fails closed when the selected RTC provider is unavailable; this does not interrupt the underlying post, workspace, place, or payment surfaces.
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.
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.