---
title: "Retrieve a role"
description: "One role in full, with its whole permission list and what currently holds it."
url: "https://openemail.uk/docs/api/roles/get"
area: "API"
category: "Roles & access"
---

# Retrieve a role

One role in full, with its whole permission list and what currently holds it.

`GET /roles/{id}`

## GET /roles/{id}

One role in full, with its whole permission list and what currently holds it.

## Example

Needs `roles:read`. Ids carry a `role_` prefix.

**curl**

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

**Response**

```
{
  "object": "role",
  "id": "role_2b81de079c1f0a4b7e05d386",
  "name": "Support",
  "description": "Answers the shared inboxes and nothing else.",
  "permissions": [
    "emails:send",
    "emails:read",
    "threads:read",
    "threads:write",
    "labels:read",
    "labels:write",
    "contacts:read"
  ],
  "builtin": null,
  "editable": true,
  "deletable": true,
  "members": 3,
  "apiKeys": 1,
  "createdAt": "2026-08-30T10:41:02.000Z",
  "updatedAt": "2026-08-30T12:15:44.000Z"
}
```

> A role on another workspace is a 404 rather than a 403, the same answer as an id that never existed, because telling a key which ids exist on a workspace it cannot read is itself the leak.

> `permissions` is the whole grant, flat and already expanded. There is nothing else to fetch and no per-permission endpoint: a role is read as one list because a list is what gets audited.

> This does not say WHO holds it. `members` and `apiKeys` are counts; the names behind the first are `GET /members`, and there is no endpoint that lists the keys on a role.