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 |
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 |
If a call fails with a missing-scope response, create a new token with the needed scope instead of reusing a broader token everywhere.
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
Custom Domains and Branded Hosts
How branded hosts are requested, what the DNS and Bind steps mean, and what changes once your domain is live.