Create Role

Create a new role or modify its permissions

Endpoint

PUT /recipe/role

This is an app-specific API that creates a new role or updates the permissions for an existing role.

Request Body

role · string · required

The name of the role to create or update. Cannot be empty or whitespace only.

permissions · string[]

Array of permission strings to assign to the role. Each permission must be a non-empty string. If not provided, the role will have no permissions.

Request Example

curl -X PUT https://your-api-domain.com/recipe/role \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "permissions": ["read:users", "write:users", "delete:users"]
  }'

Response

status · string

Always returns "OK"

createdNewRole · boolean

• true if a new role was created
• false if an existing role’s permissions were updated

Response Example

{
  "status": "OK",
  "createdNewRole": true
}

Implementation Details

Source: View source

• Role names are trimmed of leading/trailing whitespace before processing
• Permission strings are also trimmed and validated to be non-empty
• This API requires public tenant access
• If the role already exists, its permissions will be replaced with the new set

Error Responses

error · BadRequestException

Returned when:

• role field is empty or whitespace only
• Any permission in the permissions array is empty or whitespace only

Next Steps

Assign Role to User

Learn how to assign this role to users