---
search:
  tags:
    - Roles and permissions
    - PATCH
seo:
  description: >-
    Requires ac:update; replacing the Grants of a Role that… Reference for the
    PATCH /organizations/{organizationId}/roles/{roleId} endpoint in the Auth
    API.
sidebar:
  label: Rename a custom Role or replace its Grants
  badge: PATCH
title: Rename a custom Role or replace its Grants
type: openapi-operation
---
Requires ac:update; replacing the Grants of a Role that grants, or would grant, organization:delete also requires organization:delete. Grants, when present, replace every Grant of the Role. Built-in Roles cannot change (409).

`PATCH /organizations/{organizationId}/roles/{roleId}`

**Request body** (`application/json`, required)

- `name` (string) — Trimmed and lower-cased; 1 to 64 characters, not a built-in name.
- `grants` (grant_document) — A Role's Grants as scoped statements. Statements add together. Responses are canonical, one statement per scope instance.

Request body example:

```json
{
  "name": "string",
  "grants": {
    "version": 1,
    "statements": [
      {
        "scope": {
          "type": "organization",
          "ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          ],
          "all": true
        },
        "permissions": [
          "string"
        ]
      }
    ]
  }
}
```

**Responses**

- `200` — The updated Role.
- `default` — The request failed.

Response example, 200:

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "builtin": true,
  "grants": {
    "version": 1,
    "statements": [
      {
        "scope": {
          "type": "organization",
          "ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          ],
          "all": true
        },
        "permissions": [
          "string"
        ]
      }
    ]
  },
  "created_at": "2019-08-24T14:15:22Z"
}
```
