Skip to documentation

MCP scopes, ownership and private forms

Understand what an assistant can access with OAuth, personal keys and organization keys.

Updated Read as Markdown

Access is the intersection of permissions

An OAuth connection or personal key acts as a person. Inbox tools and form-management operations combine credential scopes with the person's current role and brand access. Published-form reads also enforce the credential's read scope and form visibility. Leaving the organization removes user-backed access. A guessed form or inbox ID does not bypass the relevant access checks.

An organization API key acts as the organization. It may have a brand restriction, but it does not inherit one person's private-form access. Keep broad organization keys for trusted server automation.

Scope Intended capability
forms:read Read visible form structure; a limited listing can show published forms only
forms:write Create forms and edit, publish or archive forms you created
responses:read Read submitted responses where your role and form visibility allow
feedback:read Read accessible feedback, statistics, inboxes and brands
feedback:write Submit feedback to an accessible inbox

The MCP consent scope set does not include the response-submission scope responses:write used by some partner REST integrations. Do not infer that signing in an assistant automatically grants every OAuth scope supported by Pollenate.

Personal-key and organization-key differences

Task Personal key Organization key
Read inbox feedback read, with role and brand access read or legacy MCP write
List inboxes read, with role and brand access read, write or legacy collect
Submit inbox feedback collect or write, with allowed role collect or write
Create/edit forms write, with ownership/role checks write; organization-wide key required
Read form responses read, with visibility checks read; organization-wide key required
Create or read a private form As an authorized person Not supported

An organization's admin key also grants its supported machine operations, but it still does not turn into a private form's creator. Personal keys never carry admin.

OAuth forms:write remains limited to your own forms even if your normal account role can manage other people's forms. A personal key with write can manage another non-private form only when its owner also has the relevant manage-all permission. The safest first workflow is to create a new draft with the same connection that will edit it.

Private form rules

A private form belongs to its creator. Only the creator can change its private visibility or manage its shares. A member explicitly granted access can read the form and its responses; that is not permission to edit it. Some inaccessible forms return 404 to avoid revealing their existence.

Use share_feedback_page with the member's email to grant read access and unshare_feedback_page to remove it. The recipient must already be in the organization. Organization keys cannot perform this person-owned sharing workflow.

Private form visibility protects management and results. A published form link still accepts respondents. Organization automation rules, including webhook/Zapier fan-out, do not fire for private-form responses; permitted push notifications and an opted-in creator notification follow the form's notification settings.

Diagnose a failed call

  • 401 / invalid_token: reconnect or refresh the expired/revoked credential.
  • Missing scope: approve the necessary scope or create an appropriately scoped key.
  • Role does not allow this: ask an organization administrator to review your role.
  • Cannot edit another person's form: use a form you created, or the appropriate personal-key and role workflow.
  • Brand-scoped key rejected: the form-management operation requires an organization-wide credential.
  • 404 on a known private form: ask its creator to share it with the signed-in person.

Keep authentication and the tool reference together when debugging; a valid key is only the first check.