API ReferenceAccessRoles

Update a custom role

Update a custom role’s name, description, or complete permission set and synchronize it to the identity provider.

Required permissions: role:update.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

role_idstringRequired
The ID of the custom role.

Headers

X-Penny-As-Businessstring or nullOptional

Act on behalf of another business that has granted you access. Requires the business:act_as permission.

Request

This endpoint expects an object.
namestring or nullOptional1-100 characters
A replacement role name. Omit to leave it unchanged.
descriptionstring or nullOptional1-500 characters
A replacement explanation of the role's intended access.
permissionslist of objects or nullOptional

The complete replacement permission set. Send an empty set to make the role grant no permissions. Every permission is scoped to your business; scope, sub-type, and resource-ID restrictions are not client-configurable.

Response

The updated custom role.
role_idstring

Unique identifier for this role: role_… for custom roles, global_role_… for preset roles.

versioninteger
Monotonically increasing version counter for optimistic concurrency control.
version_timedatetime
Timestamp of the most recent version update.
typeenum

Whether this is a custom role owned by your business (business) or a preset role Penny provides for every business (global).

Allowed values:
namestring

Human-readable name for the role.

descriptionstring

Human-readable description of the role’s purpose and granted access.

activeboolean
Whether this role is currently active and can be assigned.
business_idstring
The business this role is scoped to.
permissionslist of objects
The set of permissions granted to principals holding this role.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error