All docs

Tokens & abilities

What every API token ability unlocks, and how to combine them.

Updated . 7 min read.

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.
polls:read List and fetch polls and results.
polls:write Create and edit polls.
polls:publish Publish and unpublish polls.
polls:delete Archive and permanently delete polls.
polls:present Run live poll events (start, open, close, reveal, moderate Q&A) without being able to create or edit polls.
feedback:read Read feedback boards, posts, and the roadmap.
feedback:write Create and edit boards and posts.
feedback:moderate Change post status, merge, and moderate comments.
feedback:publish Publish changelog announcements.
feedback:delete Delete boards, posts, and comments.
desk:read Read Response Desk threads and analytics.
desk:reply Reply to customers from the Response Desk.
desk:assign Assign, resolve, and route threads.
desk:admin Manage Response Desk channels, macros, and settings.
contacts:read List and fetch contacts.
contacts:write Create, edit, merge, and delete contacts.
crm:read Read the CRM data model and the records of every object, standard or custom. contacts:read also grants it.
crm:write Create and change custom objects, fields, relations, views, and records. contacts:write also grants it.
action-classes:read List in-app survey triggers.
action-classes:write Create and edit in-app survey triggers.
segments:read List and preview audience segments.
segments:write Create and edit audience segments.
data-tables:read List data tables and read their rows.
data-tables:write Create, rename, and delete data tables and push rows into them.
sdk-keys:read List website SDK keys.
sdk-keys:write Create and revoke website SDK keys.
displays:read Read survey impressions and delivery analytics.
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.
funnels:delete Restore and permanently delete funnels.
funnels:export Export funnel submissions.
funnels:reveal Reveal encrypted sensitive funnel answers.
links:read List, fetch short links.
links:write Create, update, delete short links.
links:analytics:read Read short link click analytics.
bio:read List and fetch bio pages.
bio:write Create and edit bio pages and blocks.
bio:analytics:read Bio page views, visitors, and clicks.
bio:audience:export Export and sync the bio page audience (personal data).
bookings:read Read booking pages, appointments, and calendars.
bookings:write Create and edit booking pages; approve, decline, and cancel appointments; manage calendars.
bookings:publish Publish and unpublish booking pages.
bookings:delete Delete, restore, and permanently delete booking pages.
orders:read Read orders, line items, refunds, disputes, and payment totals.
orders:refund Ask the payment provider to refund a form or funnel order.
knowledge:read Read knowledge base articles and collections.
knowledge:write Create and edit knowledge base articles, collections, and help-center settings.
support:write Contact Formspring support.
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).
billing:write Change subscription, apply coupons, buy credit packs. Team owners only.
insights:read Read AI insights. Plan-gated: Pro and above.
insights:write Trigger regeneration. Plan-gated: Pro and above.
account:read Read your profile, dashboard summary, workspace search, and setup guide.
account:write Update setup guide progress.
projects:read List and read projects.
projects:write Create, edit, and restore projects.
projects:delete Archive and permanently delete projects.
team:read Read workspace settings and theme.
team:write Change workspace settings, theme, and address; create workspaces.
team:delete Delete the workspace.
members:read Read members and invitations.
members:write Invite, remove, and change roles of members.
approvals:read Read approval requests, and the rollouts staged in a client workspace.
approvals:write Approve or reject approval requests, and approve or reject a rollout staged in a client workspace (client admins).
sso:read Read single sign-on settings.
sso:write Manage single sign-on connections and domains.
email:read Read email sending settings.
email:write Manage the mail server and sending domain.
agency:read Read agency settings, client workspaces, the client portal, bundles and rollouts, client reports and the agency overview.
agency:write Manage client workspaces, project assignment, the client portal, bundles and rollouts, and scheduled client reports.
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

A token is bound to the workspace it was created in (team_id in the token list) and keeps acting there when you switch workspace in the dashboard. Cross-team reads return 404. Switch to the right workspace before creating a token you will use against it. Tokens created before binding existed have team_id: null and follow your current workspace; create a new token to bind it. If you leave the workspace, its tokens answer 403 token_workspace_unavailable.

Code examples

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