Skip to content
Tilecast Docs

updateRole

PATCH
/api/v1/roles/{key}
curl --request PATCH \
  --url https://example.com/api/v1/roles/owner \
  --header 'Content-Type: application/json' \
  --header 'X-CSRF-Token: example' \
  --data '{ "name": "example", "description": "example", "capabilities": [ "example" ] }'

Replace a custom role’s name, description, and capabilities. Built-in roles cannot be changed. The change applies to every account on the role at its next request. Requires the roles.manage capability, the admin scope, and authority to grant both the old and the new capabilities. Cookie-authenticated unsafe requests require X-CSRF-Token.

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
key
required

Role key. The built-in roles are owner, administrator, editor, contributor, and viewer. Custom role keys start with “custom.”. Decide authorization from the capabilities the server reports, not from the role key.

string
/^[a-z][a-z0-9.-]{1,63}$/

Header Parameters

Section titled “Header Parameters”
X-CSRF-Token
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
>= 2 characters <= 60 characters
description
string
<= 280 characters
capabilities
required
Array<string>
Examplegenerated
{
  "name": "example",
  "description": "example",
  "capabilities": [
    "example"
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “200”

Role updated

Media typeapplication/json
object
data
required
object
key
required

Role key. The built-in roles are owner, administrator, editor, contributor, and viewer. Custom role keys start with “custom.”. Decide authorization from the capabilities the server reports, not from the role key.

string
/^[a-z][a-z0-9.-]{1,63}$/
name
required
string
description
required
string
builtin
required
boolean
capabilities
required
Array<string>
userCount
required

Active accounts on the role.

integer
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
editable
required

Whether the caller may change or delete the role.

boolean
assignable
required

Whether the caller may place accounts on the role.

boolean
Example
{
  "data": {
    "key": "owner"
  }
}

400

Section titled “400”

Invalid request body

401

Section titled “401”

Dashboard authentication required

403

Section titled “403”

Insufficient role or capability outside the caller’s authority

404

Section titled “404”

Role not found

409

Section titled “409”

Built-in role or name already in use

422

Section titled “422”

Name, description, or capability set invalid