Skip to main content
POST
/
v1
/
auth
/
roles
Create Role
curl --request POST \
  --url https://api.example.com/v1/auth/roles \
  --header 'Content-Type: application/json' \
  --data '
{
  "realm_id": "<string>",
  "name": "<string>",
  "permissions": [
    {}
  ]
}
'
{
  "name": "<string>",
  "permissions": [
    {}
  ],
  "error": "<string>"
}

​
Overview

Roles define collections of permissions that can be assigned to users. Each role belongs to a specific realm and contains a list of permission strings. Users inherit all permissions from their assigned roles.

​
Request Body

​
realm_id
string
required
The realm identifier where this role will be created.
​
name
string
required
Unique role name within the realm.
​
permissions
array
required
Array of permission strings attached to this role. Permissions are arbitrary strings that define what actions this role can perform.

​
Response

Returns the created role object:
​
name
string
The role name.
​
permissions
array
Array of permission strings attached to the role.

​
Example

cURL
curl -X POST http://localhost:8080/v1/auth/roles \
  -H 'Content-Type: application/json' \
  -d '{
    "realm_id": "acme",
    "name": "admin",
    "permissions": [
      "users:read",
      "users:write",
      "users:delete",
      "reports:read"
    ]
  }'
Response
{
  "name": "admin",
  "permissions": [
    "users:read",
    "users:write",
    "users:delete",
    "reports:read"
  ]
}

​
Permission Design

Permissions are free-form strings. Common patterns include:
  • Resource-action format: resource:action (e.g., users:read, reports:write)
  • Hierarchical: service.resource.action (e.g., api.users.delete)
  • Wildcard: users:* or *:read

​
Error Responses

​
error
string
Human-readable error message when the request fails.
Common errors:
  • 400 Bad Request: Invalid request format or missing required fields
  • 404 Not Found: Realm does not exist
  • 500 Internal Server Error: Role creation failed due to internal error

Build docs developers (and LLMs) love

Get started for freeTalk to us