<!-- https://developers.silktide.com/v1/platform/roles/create-role | Platform / Roles -->

# 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

### Body

- `role` (object, required): The new role.
  - `displayName` (string, required, 1 to 80 characters): The role's name. Spaces at either end are removed, and a longer name is cut to 80 characters.
  - `description` (string, optional, up to 200 characters): What the role is for. Defaults to empty.
  - `icon` (string, optional, up to 80 characters): A [Font Awesome](https://fontawesome.com/icons) icon class, such as `fas fa-users`. Defaults to none.
  - `colorScheme` (string, optional): The color Silktide shows the role in. Defaults to none, and so does a value not listed here. One of: `sky`, `emerald`, `amber`, `rose`, `orange`, `violet`, `indigo`, `cyan`, `fuchsia`, `slate`.

## Response

Status `200`.

- `role` (object, required): The role.
  - `roleId` (integer, required, at least 1): The role's id. Its assignee id is `g:` and this, such as `g:2`.
  - `displayName` (string, required): The role's name.
  - `icon` (string, required): A [Font Awesome](https://fontawesome.com/icons) icon class, such as `fas fa-globe`. Empty when it has none.
  - `colorScheme` (string, required): The color Silktide shows the role in. Empty when it has none. One of: `sky`, `emerald`, `amber`, `rose`, `orange`, `violet`, `indigo`, `cyan`, `fuchsia`, `slate`.
  - `description` (string, required): What the role is for. Can be empty.
  - `created` (integer, required): 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. |
| 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. |
| 503 | - | Silktide is busy. Retry after the number of seconds in the `Retry-After` header. |

## Access

- Permission: Can admin users and groups
- Plan feature: none
- Edition: Silktide 4 and Silktide 5
- Cost: free
- Stability: stable, since 1.0.0

## Example: Create a role for web editors

```bash
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:

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