Skip to content
Tilecast Docs

createRole

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

Create a custom role. Requires the roles.manage capability and the admin scope. A caller other than the Owner may include only capabilities they hold, and never users.manage or roles.manage. Cookie-authenticated unsafe requests require X-CSRF-Token.

Parameters

Section titled “ Parameters ”

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 ”

201

Section titled “201”

Role created

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

409

Section titled “409”

Role name already in use

422

Section titled “422”

Name, description, or capability set invalid