Skip to content

API reference

Roles and permissions

Read the permissions a role can have, make roles of your own, and give each person on the team the role that fits.

On this page you will learn

  • The permissions every role is built from
  • The four default roles and the ones your workspace made
  • Creating, changing and deleting roles
  • Listing members and giving one another role
  • The rules that stop anyone from giving more access than they have

Every member reads the whole workspace. A role is a set of permissions, and each permission lets its people change one part of it. The default roles (owner, admin, editor, viewer) never change; a workspace can add up to 50 roles of its own. See Roles for how they work in the dashboard.

List permissions

GEThttps://formpik.com/api/v1/permissions

Works with read only and full access keys.

cURL
curl -X GET "https://formpik.com/api/v1/permissions" \
  -H "Authorization: Bearer $FORMPIK_API_KEY"
KeyNameWhat it allows
forms.manageFormsCreate, change and delete forms, and draft them with AI.
flows.manageFlowsCreate, change, test and delete flows.
sources.manageSourcesConnect websites, give them a new endpoint address and remove them.
destinations.manageDestinationsConnect, change and disconnect chat channels and webhooks.
destinations.secretsWebhook secretsSee the full address and signing secret of every destination.
submissions.manageInboxMark spam, release, run flows again, delete and send test submissions.
members.manageTeamInvite people, resend and withdraw invitations, and remove members.
roles.manageRolesCreate, change and delete roles, and change the role of each person.
settings.manageSettingsChange the workspace name, timezone, notifications and privacy settings.
billing.manageBillingChange the plan and the card, and see invoices.
api_keys.manageAPI keys and appsCreate and revoke API keys, and see and disconnect every connected app.

List roles

GEThttps://formpik.com/api/v1/roles

The default roles first, then your own by name, each with how many people and open invitations have it.

cURL
curl -X GET "https://formpik.com/api/v1/roles" \
  -H "Authorization: Bearer $FORMPIK_API_KEY"
  • A default role has its key as its id, such as editor, and built_in true. Your own roles have ids that start with role_.
  • owner and admin have every permission. Only the owner hands the workspace over or deletes it, and that is not a permission any other role can have.

Read one role

GEThttps://formpik.com/api/v1/roles/{id}
200 OK
{
  "data": {
    "id": "role_k3x9p2m7qa",
    "name": "Support",
    "description": "Works the inbox, never changes forms or flows",
    "permissions": ["submissions.manage"],
    "built_in": false,
    "member_count": 2,
    "invitation_count": 1,
    "created_at": "2026-11-02T09:14:05.000Z",
    "updated_at": "2026-11-02T09:14:05.000Z"
  }
}

Create a role

POSThttps://formpik.com/api/v1/roles

Needs a key with admin access. Answers 201 with the role.

namestringrequired
Up to 40 characters, unique in the workspace. The names of the default roles are taken.
descriptionstring
What the role is for, up to 200 characters.
permissionsstring[]required
Permission keys from List permissions. An empty list makes a role that only reads.
cURL
curl -X POST "https://formpik.com/api/v1/roles" \
  -H "Authorization: Bearer $FORMPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support", "description": "Works the inbox, never changes forms or flows", "permissions": ["submissions.manage"] }'

Change a role

PATCHhttps://formpik.com/api/v1/roles/{id}

Needs a key with admin access. Only what you send changes.

Send name, description or permissions. permissions replaces the whole list, and everyone with the role gets the new permissions on their next request. A default role answers 403 with the code default-role.

cURL
curl -X PATCH "https://formpik.com/api/v1/roles/role_k3x9p2m7qa" \
  -H "Authorization: Bearer $FORMPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "permissions": ["submissions.manage", "forms.manage"] }'

Delete a role

DELETEhttps://formpik.com/api/v1/roles/{id}?move_to=viewer

Needs a key with admin access.

Everyone with the role, and every open invitation with it, moves to move_to first: a default role or another of your own, viewer when left out. Nobody leaves the team.

200 OK
{
  "data": {
    "deleted": true,
    "moved": 2,
    "moved_to": { "id": "viewer", "name": "Viewer" }
  }
}

Read one member

GEThttps://formpik.com/api/v1/members/{id}

Needs a key with admin access. The whole team, with the invitations, is List the team.

200 OK
{
  "data": {
    "id": "5f0c2d1e-8a3b-4c7d-9e2f-1a6b3c8d4e70",
    "user_id": "2b7e9c4a-1d3f-4e8a-b6c2-9f0d1e3a5b7c",
    "name": "Ana Silva",
    "email": "ana@northwind.studio",
    "role": "role_k3x9p2m7qa",
    "role_name": "Support",
    "permissions": ["submissions.manage"],
    "owner": false,
    "joined_at": "2026-10-14T12:01:33.000Z",
    "last_active_at": "2026-11-20T16:45:10.000Z"
  }
}

Give a member another role

PATCHhttps://formpik.com/api/v1/members/{id}

Needs a key with admin access. Answers with the member.

rolestringrequired
A role id: admin, editor, viewer, or one of your own (role_...). Never owner.
cURL
curl -X PATCH "https://formpik.com/api/v1/members/5f0c2d1e-8a3b-4c7d-9e2f-1a6b3c8d4e70" \
  -H "Authorization: Bearer $FORMPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "role_k3x9p2m7qa" }'

What nobody can do

  • Give a role, or a person, a permission they do not have themselves. An admin key has every permission an admin has; an agent signed in with a link has the permissions of the person who connected it, within the access it was given.
  • Change or delete a role, or change someone's role, when it has permissions they lack.
  • Change the owner's role, give anyone the owner role or hand the workspace over. The owner does that on the Members page.
  • Delete the workspace. That stays with the owner in the dashboard.
403 Forbidden
{
  "message": "You cannot give someone Finance: it includes Billing, which your role does not have.",
  "code": "permission-escalation"
}

Common questions

Can a role hide submissions?
No. Every role reads the whole workspace. Permissions decide what someone can change.
Can an AI agent manage roles?
Yes. The MCP server has the same tools: list_permissions, list_roles, get_role, create_role, update_role, delete_role, list_members, get_member and change_member_role.
What happens to people when I take a permission away?
They lose it on their next request, everywhere: the dashboard, their API calls and their connected agents.

Next steps