Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us