Tokens & abilities

Every API token holds a list of abilities. Each endpoint in the REST API and each tool in the MCP server lists the ability it requires. The token's abilities are the upper bound - a request without the right ability is rejected with 403 before any logic runs.

The REST API and MCP server share this permission model. A token that can call GET /api/v1/forms with forms:read can also call the MCP form-reading tools; without that ability both surfaces reject the request before touching form data.

Abilities are independent of plan

Token abilities are independent of plan. A token may carry surveys:write on Free, but /api/v1/surveys returns 404 until the team upgrades to a plan that includes surveys. The same rule applies to any plan-gated resource (surveys, funnels, AI insights, custom retention): the ability is yours to mint, but the underlying resource is gated by the plan and answers 404 until you upgrade.

The REST API and MCP server themselves are available on every plan. Free is scoped to forms, submissions, links, and automations; Pro and above unlocks surveys, funnels, AI insights, and webhooks over both surfaces.

All abilities

Ability	Powers
`forms:read`	List, fetch forms.
`forms:write`	Create, update, publish, unpublish, archive, restore, force-delete.
`forms:test-email`	Send test autoresponder / notification emails (no submission stored).
`submissions:read`	Read submissions, files, signed URLs.
`submissions:write`	Update, delete, bulk action.
`submissions:export`	CSV / JSON exports.
`webhooks:read`	List webhooks, deliveries. Plan-gated: Pro and above.
`webhooks:write`	Create, update, delete, replay. Plan-gated: Pro and above.
`surveys:read`	List, fetch surveys and their screens. Plan-gated: Pro and above.
`surveys:write`	Create, update, publish, unpublish, delete surveys. Plan-gated: Pro and above.
`funnels:read`	List, fetch funnels. Plan-gated: Pro and above.
`funnels:write`	Create, update, delete; funnel authoring tools. Plan-gated: Pro and above.
`funnels:publish`	Publish or unpublish funnels. Plan-gated: Pro and above.
`funnels:analytics`	Funnel analytics and sessions. Plan-gated: Pro and above.
`links:read`	List, fetch short links.
`links:write`	Create, update, delete short links.
`automations:read`	List automations and runs.
`automations:write`	Create, update, enable, disable, delete automations.
`automations:run`	Manually trigger or replay automation runs.
`billing:read`	Plan, usage, subscription state (MCP + API).
`insights:read`	Read AI insights. Plan-gated: Pro and above.
`insights:write`	Trigger regeneration. Plan-gated: Pro and above.
`tokens:read`	List your own tokens.
`tokens:write`	Mint and revoke tokens; new tokens cannot exceed your own abilities.

Sensible token sets

Read-only dashboard scrape

text

forms:read
submissions:read
billing:read

Spam triage agent

text

forms:read
submissions:read
submissions:write

Backend service that creates submissions and forwards them

text

forms:read
submissions:read
webhooks:read
webhooks:write

Admin-grade automation

text

forms:read forms:write forms:test-email
submissions:read submissions:write submissions:export
webhooks:read webhooks:write
billing:read insights:read insights:write
tokens:read tokens:write

Token minting from a token

tokens:write can mint child tokens. The child's abilities must be a subset of the parent's; the API rejects any escalation attempt with 403. This means an admin token can hand out scoped read-only tokens to your team without giving each one full power.

Cross-team

Tokens are minted in a team. Cross-team reads return 404. Switch teams in the dashboard before minting tokens you'll use against a different workspace.

Code examples

See API examples → for JavaScript, Python, and Go snippets that show the required ability set beside each workflow.