Skip to main content
DELETE
Revoke a role
Revokes one role from a holder at exactly the scope named (orgUnitId, or the platform scope when absent); a grant at another scope is untouched, and nothing is deleted. The same rule as giveRole applies: the calling credential must hold every permission of the role where the grant is, counted from its own grants narrowed by its scopes, may not revoke its own grants, and may not revoke the last Platform admin. A refusal is 403 forbidden with each reason in error.refusals. changed is false when there was nothing to revoke. The audit trail records the change, the credential and reason. See Roles and grants.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without changing anything again.

Required string length: 1 - 255

Path Parameters

holderId
string
required

The holder's id: a person's id, an agent definition's id, an API key's id or an External App's id, as listGrants returns them.

Minimum string length: 1
roleKey
string
required

The role, by key (listRoleDefinitions).

Minimum string length: 1

Body

application/json

Revoke one role from one holder at exactly the scope named.

actorKind
enum<string>
required

The holder's kind: a person, an agent, an API key or an External App.

Available options:
person,
agent,
api_key,
external_app
orgUnitId
string

The org unit the grant is at. Absent: the platform scope.

Minimum string length: 1
reason
string

Why, in your words; recorded on the audit event, never returned by a read (at most 280 characters).

Maximum string length: 280

Response

Revoke a role

data
object
required

changed is false when the holder held no enabled grant of the role at that scope. orgUnitId is the scope (null: the platform scope).

meta
object
required