All docs

Authentication

How tokens, abilities, and team scoping work.

Updated . 9 min read.

The MCP server uses the same API tokens as the REST API. Every request carries the token in the Authorization header; each tool checks the token holds the right ability before running.

Mint a token

  1. Open API tokens.
  2. Click Create token, name it (e.g. "Claude Code").
  3. Pick the abilities. Less is more - you can always mint another.
  4. Copy the value. It's shown once.

Set it in your client config (Authorization: Bearer ... for HTTP, AUTH_TOKEN env var for stdio).

Abilities

Ability Powers
forms:read List, fetch forms; framework integration catalog
forms:write Create, update, publish, archive, restore
forms:test-email Send test autoresponder / notification emails
submissions:read Read submissions, files, signed URLs, form stats
submissions:write Update, delete, bulk action, mark spam
submissions:export Inline JSON export (up to 500 rows)
webhooks:read List webhooks and deliveries (Pro and above)
webhooks:write Create, update, delete, replay (Pro and above)
surveys:read List, fetch surveys (Pro and above)
surveys:write Create, update, publish, unpublish, delete surveys (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, rotate and revoke website SDK keys.
displays:read Read survey impressions and delivery analytics.
funnels:read List, fetch funnels (Pro and above)
funnels:write Create, update, delete; add screens/blocks; set logic, score, pixels, CAPI (Pro and above)
funnels:publish Publish or unpublish a funnel (Pro and above)
funnels:analytics Funnel analytics and session lists (Pro and above)
funnels:delete Restore and permanently delete funnels
funnels:export Export funnel submissions
funnels:reveal Reveal encrypted sensitive funnel fields
links:read List, fetch short links (all plans)
links:write Create, update, delete short links (all plans)
links:analytics:read Read link 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 audience (personal data)
bookings:read Read bookings (pages, appointments, calendars)
bookings:write Create and edit booking pages, manage appointments and 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
knowledge:write Manage knowledge base and help center
support:write Contact Formspring support
automations:read List automations, runs, run details (all plans)
automations:write Create, update, enable, disable, delete automations (all plans)
automations:run Manually trigger or replay automation runs (all plans)
billing:read Team summary, plan, usage, subscription state
billing:write Manage subscription, coupons and credit packs (team owner)
insights:read Read AI insights (Pro and above)
insights:write Trigger regeneration (Pro and above)
account:read Read profile, dashboard, search and setup guide
account:write Update setup guide progress
projects:read 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
approvals:write Approve or reject approval requests
sso:read Read single sign-on settings
sso:write Manage single sign-on
email:read Read email sending settings
email:write Manage SMTP and sending domain
agency:read Read agency settings, client workspaces and the agency portal
agency:write Manage client workspaces, project assignment and the agency portal
tokens:read List your own tokens
tokens:write Mint and revoke tokens (subset of caller's abilities)

Abilities are independent of plan: you can mint surveys:write on Free, but survey tools are hidden from tools/list and return plan errors if invoked. The in-app setup wizard defaults to every ability except the sensitive ones: tokens:write, team:delete, billing:write, members:write, sso:write, email:write, funnels:reveal, and bio:audience:export. Tick those on only when the agent needs them.

Plan vs. ability

  1. Ability - does the token include what the tool needs?
  2. Plan - does the team's subscription include the product (surveys, funnels, webhooks, AI)? Paid-only tools, resources, and prompts are filtered out of list responses on Free.
  3. Policy - for mutations, does the user have the dashboard permission?
  4. Team - does the record belong to the calling team?

Miss any check and the tool refuses (or never appears in the client's tool picker).

Team scoping

Every token is minted in one workspace and stays bound to it: it keeps acting in that workspace even after you switch to another one in the dashboard, and it is refused if you leave the workspace. Cross-team lookups return "not found" (not "forbidden") so an agent can't enumerate other teams. Older tokens that were minted before binding existed keep following your current workspace; mint a new token to bind it. The API token list shows each token's team_id.

Ask me before risky actions

A token can wait for your approval before it does anything risky. When that is on, the first time the token calls a risky tool nothing runs. The tool result tells the assistant where you approve the call, and it runs only after you do.

It is on by default for:

  • tokens created by the device sign-in flow and the in-app setup wizard,
  • the Ask me before this token does anything risky box when you create a token in the dashboard (untick it if you want the token to run on its own),
  • tokens an assistant creates with the create_token tool (it can pass confirm_destructive: false to opt out, unless its own token needs approval; a token that needs approval only ever creates tokens that need it too).

Tokens created through POST /api/v1/tokens ask only when you send confirm_destructive: true.

Risk classes

Every tool has one risk class, shown on the approval page. Reads and ordinary edits never wait. The other five classes always do, for a token that asks for approval:

Risk class What it covers Examples
read Reads only. Never waits. list_forms, get_submission
write Ordinary edits you can change or undo. Never waits. create_form, update_contact, publish_form
destructive Deletes, overwrites wholesale, revokes or rolls back. delete_contact, force_delete_form, bulk_submissions, merge_contacts
external_send Reaches people or systems outside your workspace. reply_desk_thread, send_contact_email, send_survey_wave, send_signing_request, invite_portal_client, replay_webhook_delivery
financial Moves money, changes a subscription or records revenue. subscribe_to_plan, purchase_ai_credit_pack, request_booking_balance, refund_booking_payment
credential Creates, rotates, stores or reveals a key, secret, token or sending setup. create_token, rotate_webhook_secret, update_smtp_config, set_sending_domain, connect_issue_tracker
access_control Changes who can get in or what they may do. invite_team_member, update_team_member_role, remove_team_member, create_sso_connection

A tool that has not been given a class is treated as risky until it is classified, so a new tool never skips approval by accident. The class is separate from the ability: the ability (forms:write, billing:write and so on) decides whether the token may call the tool at all; the class decides whether you also have to approve each call.

What the assistant sees

json
{
  "error": "confirmation_required",
  "confirmation_id": "cnf_01j...",
  "confirm_url": "https://formspring.io/mcp/confirm/cnf_01j...",
  "expires_at": "2026-10-27T10:15:00+00:00",
  "risk_class": "external_send",
  "abilities": ["desk:reply"],
  "summary": { "thread_id": "thr_123", "body": "Hello..." }
}

You open confirm_url while signed in and approve or decline. The page shows the tool, the kind of action, the permission it needs and the arguments (anything that looks like a secret is hidden). After you approve, the assistant calls the same tool again with the same arguments plus confirmation_id, and it runs once.

An approval is tied to you, to that token, to that tool and to those exact arguments. It expires after 15 minutes and cannot be used twice. Changing even one character of the arguments needs a new approval. Text inside the arguments, such as a note that claims you already approved, never counts: only you can approve, and only from your signed-in browser session, never with a token. If the token does not hold the ability the tool needs, an approved call is still refused.

Reviewing tokens you already have

Tokens created before approval became the default keep working exactly as they did. Open API tokens: tokens that run without asking are flagged, and Ask first switches approval on for a token. You can also turn it off again with Stop asking. A token cannot change this setting for itself.

Local subprocess transport

The local transport that some desktop clients start as a subprocess has no signed-in user, so it refuses every tool call. Connect over the hosted endpoint with a token or the device sign-in flow instead.

Revocation

Pull a token from API tokens in one click. The next call from the agent fails. No grace period.

Refusal message

text
Token missing required ability `submissions:write`.

The agent sees this in the tool result and either asks you, or falls back to a tool that's in scope.