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
https://formpik.com/api/v1/permissionsWorks with read only and full access keys.
curl -X GET "https://formpik.com/api/v1/permissions" \
-H "Authorization: Bearer $FORMPIK_API_KEY"| Key | Name | What it allows |
|---|---|---|
forms.manage | Forms | Create, change and delete forms, and draft them with AI. |
flows.manage | Flows | Create, change, test and delete flows. |
sources.manage | Sources | Connect websites, give them a new endpoint address and remove them. |
destinations.manage | Destinations | Connect, change and disconnect chat channels and webhooks. |
destinations.secrets | Webhook secrets | See the full address and signing secret of every destination. |
submissions.manage | Inbox | Mark spam, release, run flows again, delete and send test submissions. |
members.manage | Team | Invite people, resend and withdraw invitations, and remove members. |
roles.manage | Roles | Create, change and delete roles, and change the role of each person. |
settings.manage | Settings | Change the workspace name, timezone, notifications and privacy settings. |
billing.manage | Billing | Change the plan and the card, and see invoices. |
api_keys.manage | API keys and apps | Create and revoke API keys, and see and disconnect every connected app. |
List roles
https://formpik.com/api/v1/rolesThe default roles first, then your own by name, each with how many people and open invitations have it.
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, andbuilt_intrue. Your own roles have ids that start withrole_. ownerandadminhave 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
https://formpik.com/api/v1/roles/{id}{
"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
https://formpik.com/api/v1/rolesNeeds 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 -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
https://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 -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
https://formpik.com/api/v1/roles/{id}?move_to=viewerNeeds 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.
{
"data": {
"deleted": true,
"moved": 2,
"moved_to": { "id": "viewer", "name": "Viewer" }
}
}Read one member
https://formpik.com/api/v1/members/{id}Needs a key with admin access. The whole team, with the invitations, is List the team.
{
"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
https://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_...). Neverowner.
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.
{
"message": "You cannot give someone Finance: it includes Billing, which your role does not have.",
"code": "permission-escalation"
}