Authentication
Postforge workspace API keys, their scopes, and how to rotate and revoke them.
Postforge's API accepts workspace API keys as bearer tokens:
Authorization: Bearer pf_…Workspace keys
- A key belongs to one workspace; every request with it works in that workspace only.
- Keys are stored as a SHA-256 hash and shown once, when created or rotated.
- Everyone in the workspace sees the list under Developers → API keys; owners and admins create, rotate and revoke them. The list shows when each key was last used.
Scopes
Each key has one scope, and each scope includes the ones before it:
| Scope | Can |
|---|---|
read | Read data: profiles, orders, products, coupons, definitions, … |
propose | Everything read can, plus create change proposals that a person approves |
write | Everything propose can, plus create, change and delete |
Operations that manage the team, API keys or workspace ownership never accept keys: they need a
person signed in to the dashboard. The API reference marks which operations
accept keys; a key with too small a scope gets a 403 problem with code scope.
Rotating and revoking
- Rotate gives a key a new secret with the same name and scope; the old secret stops working at once.
- Revoke stops a key for good; it stays listed so you can see what it was.
Rotate a key whenever it may have leaked, and give every integration its own key so you can revoke one without breaking the others.
AI clients
AI clients will connect to the MCP server with OAuth 2.1, acting with the
signed-in person's role in the workspace they choose. Until it is live, agents use a workspace
key; a propose key keeps every change behind a person's approval.