Create a role

POST/v1/roles

Creates a role, with no permissions and no members. Give it both in Silktide.

Only displayName is required. Older documentation said description was required too; it is not.

The API cannot change or delete a role once it is made, so check the name before you send it. A name longer than 80 characters is not refused: it is cut short.

Request

curl -X POST "https://api.eu.silktide.com/v1/roles" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "role": {
    "displayName": "Web editors",
    "description": "Fix issues on the public websites",
    "icon": "fas fa-pen",
    "colorScheme": "violet"
  }
}'

Response: Create a role for web editors

{
  "role": {
    "roleId": 3,
    "displayName": "Web editors",
    "icon": "fas fa-pen",
    "colorScheme": "violet",
    "description": "Fix issues on the public websites",
    "created": 1791431526
  }
}

Request

Body

JSON, sent with Content-Type: application/json.

roleobjectrequired
The new role.
Show 4 fieldsHide fields
- displayNamestringrequired1 to 80 characters
  The role's name. Spaces at either end are removed, and a longer name is cut to 80 characters.
- descriptionstringup to 200 characters
  What the role is for. Defaults to empty.
- iconstringup to 80 characters
  A Font Awesome icon class, such as fas fa-users. Defaults to none.
- colorSchemestring
  The color Silktide shows the role in. Defaults to none, and so does a value not listed here.
  One ofskyemeraldamberroseorangevioletindigocyanfuchsiaslate

Response

200JSON.

roleobjectrequired
The role.
Show 6 fieldsHide fields
- roleIdintegerrequiredat least 1
  The role's id. Its assignee id is g: and this, such as g:2.
- displayNamestringrequired
  The role's name.
- iconstringrequired
  A Font Awesome icon class, such as fas fa-globe. Empty when it has none.
- colorSchemestringrequired
  The color Silktide shows the role in. Empty when it has none.
  One ofskyemeraldamberroseorangevioletindigocyanfuchsiaslate
- descriptionstringrequired
  What the role is for. Can be empty.
- createdintegerrequired
  When the role was created.

Errors

Status	Type	When
403	`AccessDenied`	The API key's user cannot admin users and groups.
400	`OutOfBounds`	`role.displayName` is missing or empty.
401	`NotLoggedIn`	No API key was sent, or it is not a key for this region.(any operation)
429	`TooManyRequests`	Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats.(any operation)
503	-	Silktide is busy. Retry after the number of seconds in the `Retry-After` header.(any operation)

Every error has the same body. See Errors.

Access

Permission: Can admin users and groups
Plan feature: None
Edition: Silktide 4 and Silktide 5
Cost: Free
Available since: v1.0.0

Try it

Sends a real request to your account from this browser. Your key stays in this tab and goes only to the Silktide API.

Request

curl -X POST "https://api.eu.silktide.com/v1/roles" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "role": {
    "displayName": "Web editors",
    "description": "Fix issues on the public websites",
    "icon": "fas fa-pen",
    "colorScheme": "violet"
  }
}'

Response: Create a role for web editors

{
  "role": {
    "roleId": 3,
    "displayName": "Web editors",
    "icon": "fas fa-pen",
    "colorScheme": "violet",
    "description": "Fix issues on the public websites",
    "created": 1791431526
  }
}

Try it

Sends a real request to your account from this browser. Your key stays in this tab and goes only to the Silktide API.