Role

Retrieve, Create, Edit, and Delete Role

Manages roles for the specified application. Depending on the action parameter, this endpoint retrieves, creates, updates, or deletes a role.

Access Requirements

The request author must have secret_data.application.canReadSchema to read the role schema, or secret_data.application.canModifySchema to create or update it. Alternatively, a positive rule for projectID/project.can_manage_applications is also sufficient.

Note

When adding a role with the name "default", all rules within this role will automatically be applied to all users of the application. Additionally, if a role has the default=true flag, it will be applied to all users without exception.

Request

POST /api/permissions/roles

Warning

Passing jwt, factor, and service_jwt in the request body is deprecated. Use the corresponding HTTP headers instead.

jwt string required 

User’s JWT token.
factor string conditionally required 

User device factor. Required if service_jwt is not provided.
service_jwt string conditionally required 

Service JWT. Required if factor is not provided.
action string required 

Action to perform. Allowed values: "get", "save", "delete".
application_id string or integer required 

ID of the application for which the role is being managed.
data object required 
- name string required 
  
  Role name.
- meta object optional 
  
  Role schema. Provided only for the "save" action.
- description string optional 
  
  Brief description of the role.
- protected boolean optional 
  
  Whether the role is a protected role. See Protected Role Restrictions.
- default boolean optional 
  
  If true, the role is applied to all users without exception. Defaults to false.
- condition object optional 
  
  Logical role conditions for role applicability. See Conditions.
- user_limit integer optional 
  
  Maximum number of users that can be assigned this role. Set to a value greater than zero to enable the limit.
- params string optional 
  
  Additional parameters, separated by commas (e.g., "tag0,tagN"). These are appended to each rule in the role schema when the role is deployed to a user’s schema. Parameters are combined when rules overlap across roles.

Request example (save)

POST /api/permissions/roles

Headers

Authorization: Bearer eyJhbGci...
Factor: ...

Body

{
  "action": "save",
  "application_id": 50001,
  "data": {
    "name": "editor",
    "description": "Can edit content",
    "protected": false,
    "default": false,
    "condition": {
      "domain": "example.com"
    },
    "user_limit": 10,
    "params": "tag0,tag1"
  }
}

Response

OK

Success

status string required 
- “OK”
data object optional 

Returned for the "get" action only.
- application_id string or integer required 
  
  ID of the application the role belongs to.
- name string required 
  
  Role name.
- meta object optional 
  
  Role schema.
- description string optional 
  
  Brief description of the role.
- protected boolean required 
  
  Whether the role is protected. Defaults to false.

Response example (get)

{
  "status": "OK",
  "data": {
    "application_id": 50001,
    "name": "editor",
    "meta": {},
    "description": "Can edit content",
    "protected": false
  }
}

Response example (save/delete)

{
  "status": "OK"
}

ERROR

Error

status string required 
- “ERROR”
error string required 

Descriptive error message.

Response example

{
  "status": "ERROR",
  "error": "role not found"
}

Protected Role Restrictions

A role can be marked as protected.

Only protected roles can include protected rules from the application schema. Attempting to add a protected rule to a public role schema returns an error.
A role cannot be changed from protected to a regular role if it contains protected rules from the base application schema.
Changing a role from public to protected removes that role from user records in project access.

Conditions

The following fields are supported in the condition object. All fields are optional and can be combined using logical operators.

domain string optional 

Compares the user’s login domain with the specified value.
uid array of strings optional 

Checks if the user ID is in the specified list.
tag string optional 

Checks if a tag exists.
ip string optional 

Compares the client’s IP address with the specified value. Must be in CIDR format.
purchase string optional 

Verifies the existence of a purchase.
everyone boolean optional 

If true, grants access to all users.
and array of objects optional 

Logical AND operator. Supports any level of nesting.
or array of objects optional 

Logical OR operator. Supports any level of nesting.

Example:

"condition": {
  "and": [{"tag": "2step"}, {"tag": "email_verified"}],
  "ip": "192.168.65.1/32",
  "purchase": "9B7F9924-1778-4DA6-9F50-6FC5F43B636E",
  "everyone": true,
  "or": [{"domain": "gaijin.team"}, {"domain": "example.com"}],
  "uid": ["1", "2", "3"]
}