permissionAndRoleManagement

Update a custom role

<Info icon="fa-light fa-lock" className="permission-callout"> <div className="permission-callout__header"><span className="permission-callout__title"><span className="permission-callout__label">Required permissions</span> <span className="fern-docs-badge small blue subtle rounded-full permission-callout__beta">Beta</span></span> <span className="permission-callout__learn-more">[Learn more](/developers/api-guidelines/permissions#how-permissions-work)</span></div>

Organisation.Role + Update

<div className="permission-callout__roles"><span className="permission-callout__roles-label">Roles:</span> <Badge intent="info">Administrator</Badge></div> </Info>

Partially updates a custom role. System roles can't be modified.

When you provide permission_ids or permissions, the field replaces the existing permission list. The two fields are mutually exclusive. Retrieve the valid permissions with GET /api/v1/organisation/{orgId}/permission.

Use my in place of a numeric orgId to target the caller's own Workspace.

patch/api/v1/organisation/{orgId}/role/{roleId}

Request

  • Base URL: https://cdn.emnify.net
  • URL: https://cdn.emnify.net/api/v1/organisation/{orgId}/role/{roleId}
  • Auth: HTTP bearer

Path parameters

roleIdinteger required

Numeric identifier of the role.

integer required
OR
'my' required

Workspace identifier. Either a positive integer organization ID, or the literal string my to target the caller's own Workspace.

Request body

namestring

New unique role name within the Workspace. Use letters, digits, spaces, dashes, underscores, ampersands, and apostrophes. Leading and trailing whitespace is trimmed before validation and storage. Omit the field to leave the name unchanged, because an explicit null is rejected.

descriptionstring nullable

Free-text description of the role. Pass null to clear it, which stores an empty string. When provided, it must be 2 to 250 characters. Leading and trailing whitespace is trimmed before validation and storage.

permission_idsnumber[]

When provided, replaces the existing permission list. Mutually exclusive with permissions. Deprecated or deleted permissions are rejected. Omit the field to leave assignments unchanged, and send [] to clear them, because an explicit null is rejected.

Response

Successful response.

idnumber double required

Unique role identifier.

namestring required

Display name of the role.

name_translation_keystring nullable required

Translation key for the role name. Set for system roles only.

descriptionstring required

Human-readable description of the role. An empty string when no description has been set.

description_translation_keystring nullable required

Translation key for the role description. Set for system roles only.

user_countnumber double required

Number of users assigned to this role in the Workspace.

type'system' | 'custom' required

Whether this is a system-defined role or an organization's custom role.

is_system_roleboolean required

True for built-in system roles, which can't be modified or deleted.

Changes

No recorded changes to this operation across all 1 revision of this API.