---
title: "Read one role and what it may do"
type: reference
method: GET
path: /rest-api/roles/{roleId}.do
tag: "Users"
---

# Read one role and what it may do

`GET https://YOUR-NETWORK-DOMAIN/rest-api/roles/{roleId}.do`

The role and its permissions, as the console's role editor shows them. By default only the permissions the role actually holds, which is the answer to 'what can this role do'; 'includeNotGranted=true' adds the rows it does not hold, which is how a caller finds the name of a permission it wants to grant. Narrow a wide answer with 'group' (a group of the matrix), 'identity' (one row, exactly as the answer spells it) or 'contains' (a word of the row's name or title). Each row carries 'identity' -- the token this role's own permissions use -- the granting types each permission is currently set to, and the ones it could be set to. 'groups' lists the whole matrix's groups with their permission columns, whatever the filter. A role built on ADMIN also carries 'adminPages', the admin console pages it opens. Requires the Admin Roles & Permissions or User Roles & Permissions console permission; an ADMIN-built role needs the admin one.

## Path params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `roleId` | integer | yes | `1` |  |

## Query params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `group` | string | no | `CAMPAIGNS_MANAGEMENT` | One group of the matrix, as 'groups' names it |
| `identity` | string | no | `CAMPAIGNS` | One row, exactly as the answer spells it; a row over another role carries its id after # |
| `contains` | string | no | `targeting` | Only rows whose name or title contains this |
| `includeNotGranted` | boolean | no | `false` | Also the rows this role does not hold, which is the whole catalogue of what it could hold |

## Responses

- `200` — {success, id, name, staticRole, identity, manageable, adminPages, groups, permissions, returned, more}
- `400` — 'group' or 'identity' names nothing in this role's matrix
- `401` — Authentication error
- `403` — The caller may not see this role
- `404` — No role with that id

## Example request

```bash
curl --request GET \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/roles/1.do?group=CAMPAIGNS_MANAGEMENT&identity=CAMPAIGNS&contains=targeting' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

Source: https://epom.com/ad-server/docs/api/users/get-roles-by-role-id