Skip to main content
POST /api/v1/roles Requires roles.create permission. Creates a custom role scoped to the current organization.

​
Request body

​
key
string
required
Machine-readable identifier for the role. Must be unique within the organization. Example: release_manager.
​
name
string
required
Human-readable display name for the role. Example: Release Manager.
​
permissions
string[]
required
Array of permission strings to grant to members with this role. Example: ["flags.read", "flags.write", "rules.read", "rules.write"].

​
Response

​
role
object
required
The newly created role.

​
Errors

StatusWhen
400Request body is invalid or missing required fields
401Missing or invalid Bearer token
403Caller lacks roles.create permission
409A role with the given key already exists

​
Example

curl -X POST http://localhost:8080/api/v1/roles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "release_manager",
    "name": "Release Manager",
    "permissions": ["flags.read", "flags.write", "rules.read", "rules.write"]
  }'

{
  "role": {
    "id": "r2b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key": "release_manager",
    "name": "Release Manager",
    "is_system": false,
    "permissions": ["flags.read", "flags.write", "rules.read", "rules.write"]
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us