1. Docs
  2. API Reference
  3. Update an operational-administrator role

Update an operational-administrator role

PATCH/portal/v1/accounts/{accountSlug}/admin-roles/{adminRoleId}

Changes a custom role's name, description or is_active, or replaces its whole capabilities set. New capabilities are checked against the catalog and the role's existing scope, which cannot change. System roles answer 403, and a name already used by another role in the Account answers 409. Send the role's version in If-Match to refuse a stale edit: a mismatch answers 409 with the current role in error.data.current, and without the header the check is skipped. Requires admin_governance.manage, and the change is recorded in the audit log.

Authentication

Bearer TokenAuthorization

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

Path Parameters

accountSlugstring Required

The Account's slug. An unknown one answers 404.

adminRoleIdstring Required

Headers

  • If-Match

    Optimistic-lock version of the resource. Send the `version` field returned on read; the server rejects with 409 if the row has changed since.

Request body

application/json

namestring Optional

Administrator role name

descriptionstring Optional

Administrator role description

capabilitiesstring[] Optional

Replacement set of operational capability keys

is_activeboolean Optional

Whether the role is active

Responses

application/json

  • dataAdminRoleResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Returned object

AdminRoleResponseDtoView all properties on this resource
Request
curl -X PATCH "https://auth.canopy-io.com/portal/v1/accounts/value/admin-roles/value" \
  -H "If-Match: "3"" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "capabilities": [
      "string"
    ],
    "is_active": false
  }'
Response
{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "is_system": false,
    "system_key": "string",
    "is_active": false,
    "scope": "account",
    "capabilities": [
      "string"
    ],
    "assignment_count": 0,
    "version": 0,
    "created_at": "2026-04-20T12:00:00.000Z",
    "updated_at": "2026-04-20T12:00:00.000Z"
  }
}
 Related endpoints
GETList operational-administrator roles for the Account
POSTCreate an operational-administrator role
GETList the operational capabilities a role may grant
GETGet an operational-administrator role
DELETEDelete an administrator role
GETList the identity roles an administrator role may grant in an Environment
PUTSet the identity roles an administrator role may grant in an Environment
 Was this page helpful?

Tell us how we can improve this guide.

Canopy