---
title: "Change a role's name and permissions"
type: reference
method: POST
path: /rest-api/roles/{roleId}.do
tag: "Users"
---

# Change a role's name and permissions

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

Changes only what the call names and leaves the rest of the role as it is. 'permissions' is repeatable and each value is IDENTITY:PERMISSION:GRANTING -- the identity exactly as the read spells it, the permission as its column is named, and one of the granting types that column offers for that row (GET the role to see both). 'grantAdminPages' and 'revokeAdminPages' add and remove the admin console pages a role built on ADMIN opens. A call that breaks a rule changes nothing at all: the role has to be one the caller may manage, a permission over another role has to be over a role the caller may manage too, MANAGE_ROLE is Super-Admin's to grant, admin-only rows need the Admin Roles & Permissions page, and an admin console page can only be handed on by a caller who holds it. A page sent to a role not built on ADMIN is named in ignoredFields with the reason, because such a role opens no admin page at all. Passwords and API keys are not part of this: this operation changes what a role may do, never a credential. Requires the Admin Roles & Permissions or User Roles & Permissions console permission.

## Path params

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

## Form params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `name` | string | no | `Campaign manager` | A new name for the role |
| `permissions` | array<string> | no | `CAMPAIGNS:UPDATE:ALL` | Repeatable, each IDENTITY:PERMISSION:GRANTING |
| `grantAdminPages` | array<string> | no | `USERS_MANAGEMENT` | Admin console pages to add to a role built on ADMIN |
| `revokeAdminPages` | array<string> | no | `PREFERENCES` | Admin console pages to take away from a role built on ADMIN |

## Responses

- `200` — {success, changed:[...], ignoredFields:[...], ignoredFieldReasons:{...}}
- `400` — A triple does not parse, or names an identity, permission or granting type this row does not take
- `401` — Authentication error
- `403` — The caller may not manage this role, or may not grant what the call asks for
- `404` — No role with that id

## Example request

```bash
curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/roles/1.do' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'name=Campaign manager' \
  --data-urlencode 'permissions=CAMPAIGNS:UPDATE:ALL' \
  --data-urlencode 'grantAdminPages=USERS_MANAGEMENT'
```

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