Skip to content
API reference
/
/
Update a role

Update a role

Request

Updates a role and returns it in the same shape as reading it. Every field is optional; a request with an empty body succeeds and changes nothing.

You cannot update a role you hold yourself. Doing so is refused with a 403 and a message saying so, which is deliberate rather than an authorisation accident - it stops an administrator editing their own permissions. Have someone on a different role make the change.

A permissions object granting more than the caller's own role holds is rejected with a 422.

options is stored whole. The object you send replaces the stored one rather than merging into it, so an update carrying only options.protect_pii clears every other key under it. Send every key you want to keep.

Security
default
Path
idintegerrequired

The ID of the role.

Headers
Rosterfy-Platformstring
Bodyapplication/json
namestring

Display name of the role, up to 255 characters. This is what administrators pick from when assigning someone a role.

permissionsobject

What the role may do, as an object of permission names against true or false. The set of names is the account's own and is not enumerated here - read an existing role to see the ones available to you, and send the same shape back. A role cannot be given a permission the caller's own role does not hold; attempting it is rejected.

horizontalobject

Optional limits on which records the role may act on, as an object keyed by the area being limited. Structure is not part of the contract - build the limits in the admin console and send back what a read returns. Entries naming an area the role has no permission for are dropped rather than rejected, so a role can come back with fewer limits than were sent.

prefillArray of items

Optional values to fill in automatically on records this role creates. Structure is not part of the contract - build it in the admin console and send back what a read returns. Each attribute may appear only once.

is_lite_adminboolean

Whether the role is a lite administrator, a reduced role whose permissions are limited to a fixed subset. Setting it discards any permission outside that subset rather than rejecting the request.

codestring

Stable identifier for the role, up to 64 characters of letters, digits, hyphens and underscores; anything else is stripped. Use it to map the role to one in your identity provider when signing in through SSO. Must be unique within the account, and one is generated if you leave it empty.

is_simple_attribute_selectionboolean

Whether the admin console offers this role the simplified attribute picker instead of the full one.

is_restrictedboolean

Whether the role is limited to specific records within the areas named in access_required_modules, chosen per person rather than per role. Update only.

is_inheritableboolean

Whether accounts below this one may use the role as well as the account that owns it.

access_required_modulesArray of strings

Which areas the per-person limits apply to, as a list of area names: headcount_functional_area, headcount_functional_area_job_title, headcount_location, headcount_location_venue or headcount_user_type. Cleared unless is_restricted is set. Update only.

optionsobject
curl -i -X PUT \
  'https://developer.rosterfy.com/_mock/api-docs/openapi/api/v2/account/role/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Rosterfy-Platform: admin' \
  -d '{
    "name": "Example Role",
    "permissions": {
      "account": true,
      "account:read": true,
      "account:update": true,
      "event": true,
      "event:read": true,
      "event:create": true,
      "event:update": true,
      "user": true,
      "user:read": true,
      "user:update": true,
      "report": true,
      "report:read": true
    },
    "horizontal": "{}",
    "prefill": [],
    "is_lite_admin": 0,
    "code": "example-role",
    "is_simple_attribute_selection": 0,
    "is_restricted": 0,
    "is_inheritable": 0,
    "access_required_modules": [],
    "options": {
      "protect_pii": true
    }
  }'

Responses

Bodyapplication/json
objectobject
niceobject
relationsArray of any
permissionsobject
Response
{
  "object": {
    "id": 5,
    "name": "Example Role",
    "code": "example-role",
    "permissions": { … },
    "horizontal": null,
    "prefill": null,
    "is_system": 1,
    "is_lite_admin": 0,
    "is_simple_attribute_selection": 0,
    "is_restricted": 0,
    "is_inheritable": 0,
    "access_required_modules": null,
    "options": null,
    "created_at": "2026-06-09T05:33:39.000000Z",
    "updated_at": "2026-06-09T05:33:39.000000Z",
    "user_dashboard_id": null
  },
  "nice": {
    "rrn": "rrn:local:20101:role:5"
  },
  "relations": [],
  "permissions": {
    "read": true,
    "update": false,
    "delete": false,
    "update_message": "You cannot update a role you are assigned to.",
    "copy": true
  }
}