---
title: "List permissions"
description: "The whole vocabulary, with the sentence and the heading each entry renders under."
url: "https://openemail.uk/docs/api/roles/permissions"
area: "API"
category: "Roles & access"
---

# List permissions

The whole vocabulary, with the sentence and the heading each entry renders under.

`GET /roles/permissions`

## GET /roles/permissions

The whole vocabulary, with the sentence and the heading each entry renders under.

## Example

Needs `roles:read`. A constant, the same answer for every workspace, and the list to build a matrix from rather than transcribing it into your own code.

**curl**

```
curl "$OE/roles/permissions" -H "$AUTH"
```

**Response**

```
{
  "object": "list",
  "data": [
    {
      "object": "permission",
      "id": "emails:send",
      "label": "Send email",
      "group": "mail",
      "scope": true
    },
    {
      "object": "permission",
      "id": "members:write",
      "label": "Add and remove people, and change what they can reach",
      "group": "people",
      "scope": true
    },
    {
      "object": "permission",
      "id": "api-keys:write",
      "label": "Create and revoke API keys",
      "group": "developer",
      "scope": false
    },
    {
      "object": "permission",
      "id": "workspace:manage",
      "label": "Rename the workspace, remove domains and delete it",
      "group": "workspace",
      "scope": false
    }
  ]
}
```

> Registered BEFORE `/roles/{id}`, or `permissions` is read as a role id and every request to it 404s. `/rules/runs` carries the same note above it and `/tracking/stats` above that, both written after the same bug. Asking for a role genuinely called “permissions” therefore asks for a role and gets a 404, which is the honest answer to what was typed.

> `scope` says whether an API KEY may hold the permission at all. Five cannot (`api-keys:read`, `api-keys:write`, `billing:read`, `billing:write` and `workspace:manage`) because there is no endpoint for any of them and a key is not a person. That flag is what lets one component render both the role matrix and the key-creation checkbox list, instead of a second hand-maintained copy of which is which.

> Served rather than transcribed, for the reason the rules field list gives: a matrix built from a copied array keeps offering a permission the day one is renamed and never offers the one added last week. `group` is the heading it renders under and falls back to `other` rather than going out undefined. A permission nobody can see is a permission nobody audits.

> The order is canonical: it is the order a stored role’s `permissions` array comes back in, so a client rendering this list and a client rendering a role show the same permissions in the same sequence.

> No envelope beyond `object` and `data`. The vocabulary is closed and short, so there is no cursor and no `hasMore`, unlike every other list in the API.