Create a Role

Creates a role. name is the identifier you will address it by everywhere else — it is NOT a generated UUID and cannot be changed afterwards.

A new role grants nothing until you put permissions in it (POST /v1/roles/{id}/permissions) and give it to someone (POST /v1/roles/{id}/groups or POST /v1/roles/{id}/users). Prefer granting to a GROUP.

Failures:

• 400 — a required member is missing or malformed.
• 409 — a role with that name already exists in your organization.
• 503 IDE-0066 — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.

POST /v1/roles

Create a Role

cURL

curl --request POST \
  --url https://identity.sandbox.lerian.net/v1/roles \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "Custom Editor",
  "name": "custom-editor",
  "description": "A custom editor role"
}
'

201

{
  "createdAt": "2026-06-24T10:00:00Z",
  "description": "A custom editor role",
  "groups": [
    "<string>"
  ],
  "id": "custom-editor",
  "isEnabled": true,
  "isSystem": false,
  "name": "Custom Editor",
  "roles": [
    "<string>"
  ],
  "users": [
    "<string>"
  ]
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Body

application/json

The role to create.

displayName · string · required

Example:

"Custom Editor"

name · string · required

Example:

"custom-editor"

description · string

Example:

"A custom editor role"

Response

201

application/json

Created

createdAt · string

Example:

"2026-06-24T10:00:00Z"

description · string

Example:

"A custom editor role"

groups · string[]

id · string

Example:

"custom-editor"

isEnabled · boolean

Example:

true

isSystem · boolean

Example:

false

name · string

Example:

"Custom Editor"

roles · string[]

users · string[]