# 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

> **Who can change roles**
>
> Every key can read permissions and roles. Creating, changing and deleting roles, and reading or changing members, needs a key with admin access, which only owners and admins can create. An agent signed in with a link can do it only with admin access and a role that has every permission.

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](https://formpik.com/docs/team#roles) for how they work in the dashboard.

## List permissions

`GET https://formpik.com/api/v1/permissions`

Works with read only and full access keys.

*cURL*

```bash
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

`GET https://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*

```bash
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

`GET https://formpik.com/api/v1/roles/{id}`

*200 OK*

```json
{
  "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

`POST https://formpik.com/api/v1/roles`

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

- `name` (string, required): Up to 40 characters, unique in the workspace. The names of the default roles are taken.
- `description` (string): What the role is for, up to 200 characters.
- `permissions` (string[], required): Permission keys from List permissions. An empty list makes a role that only reads.

*cURL*

```bash
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

`PATCH 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*

```bash
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

`DELETE https://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*

```json
{
  "data": {
    "deleted": true,
    "moved": 2,
    "moved_to": { "id": "viewer", "name": "Viewer" }
  }
}
```

## Read one member

`GET https://formpik.com/api/v1/members/{id}`

Needs a key with admin access. The whole team, with the invitations, is [List the team](https://formpik.com/docs/api/team#members).

*200 OK*

```json
{
  "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

`PATCH https://formpik.com/api/v1/members/{id}`

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

- `role` (string, required): A role id: admin, editor, viewer, or one of your own (`role_...`). Never `owner`.

*cURL*

```bash
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*

```json
{
  "message": "You cannot give someone Finance: it includes Billing, which your role does not have.",
  "code": "permission-escalation"
}
```

> **An admin key can change who does what**
>
> Keep admin keys on your server, like an admin's password. Use read only keys for code that only needs to look up roles.

## 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](https://formpik.com/docs/mcp) 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

- [Workspaces and team](https://formpik.com/docs/team): Roles, invitations and seats in the dashboard.
- [Team and access](https://formpik.com/docs/api/team): Invite people, remove members and manage API keys.
- [MCP server](https://formpik.com/docs/mcp): Let an agent set up roles for you.

---

Source: https://formpik.com/docs/api/roles
