Authentication
API keys, headers, prefixes, and scopes.
Create keys in the workspace Developer → API Keys page. The secret is shown once.
Headers
Send the secret as either:
x-api-key: wbk_...or
Authorization: Bearer wbk_...Keys use the wbk_ prefix. Only the hash is stored. If you lose a secret, revoke the key and create another.
Scopes
Scopes are an append-only bitfield. ALL_ACCESS grants every current and future bit.
| Scope | Grants |
|---|---|
ALL_ACCESS | Every capability |
PROJECTS_READ / PROJECTS_WRITE | Projects |
TASKS_READ / TASKS_WRITE | Tasks |
CUSTOMERS_READ / CUSTOMERS_WRITE | Customers |
CONTACTS_READ / CONTACTS_WRITE | Contacts |
FORMS_READ / FORMS_WRITE | CRM intake forms |
PIPELINES_READ / PIPELINES_WRITE | Pipelines and deals |
INVOICES_READ / INVOICES_WRITE | Invoices |
PAYMENTS_READ / PAYMENTS_WRITE | Payments |
EXPENSES_READ / EXPENSES_WRITE | Company expenses, categories, and budgets |
CATALOG_READ / CATALOG_WRITE | Products and plans (Commerce catalog) |
COMMUNICATIONS_READ / COMMUNICATIONS_WRITE | Channels and messages |
EMBED_WRITE | Mint embed sessions and list that user's projects |
Narrower scopes cover single features. They exist mainly for community apps, and a key can hold them too:
| Scope | Grants | Also satisfied by |
|---|---|---|
EVENTS_READ | List and read events | CONTACTS_READ, CONTACTS_WRITE |
EVENT_REGISTRATIONS_WRITE | Register, cancel and set attendance | CONTACTS_WRITE |
FORMS_SUBMIT | Submit a form as a community member | FORMS_WRITE |
COMMUNITY_MESSAGES_READ | Community channels and message history | — |
COURSES_READ | Course outlines and member progress | COURSE_PROGRESS_WRITE |
COURSE_PROGRESS_WRITE | Complete or uncomplete a module for a member | — |
WRITE implies the matching READ check in the handler. A key with only FORMS_SUBMIT lists only published forms shown in community apps.
EMBED_WRITE is required for embedded projects. Mint sessions from your server — never from the browser.
Rate limits
Authenticated requests are limited to about 60 per minute per key. Exceeding that returns 429.
The same key authenticates MCP at POST /api/mcp/{workspaceId} for Claude, ChatGPT, editors, and any Streamable HTTP client. The key must belong to that workspace.
Planeward Docs