Role Groups

Download OpenAPI specification:Download

Roles can be organized into groups so you can more easily control access to your application. For example, you can add a role group to an organization for B2B scenarios so that their members can only be assigned roles that belong to this group. These APIs allow you to manage the role groups for your application. You can then use the Organizations APIs to add the relevant role groups to each organization and the Members API can be used to assign roles to their members.

Create role group

Create a new role group for this application.

Required permissions: organizations:create, roles:create.

SecurityOAuth2: AdminAccessToken
Request
path Parameters
app_id
required
string

ID of the application to create the role group in

Request Body schema: application/json
required
role_ids
required
Array of strings

Ids of the roles

name
required
string

Name of the roles group

description
string

Description of the roles group

display_name
string

Group display name

Responses
409
post/v1/applications/{app_id}/role-groups
Request samples
application/json
{
  • "role_ids": [
    ],
  • "name": "My Group",
  • "description": "My Group's description",
  • "display_name": "string"
}
Response samples
application/json
{
  • "message": "string",
  • "error_code": 0
}

Get role groups

Retrieve a list of all role groups created for this application.

Required permissions: organizations:read, roles:read, organizations:list, roles:list, orgs:read.

SecurityOAuth2: AdminAccessToken
Request
path Parameters
app_id
required
string

ID of the application to retrieve it's role groups

Responses
200
get/v1/applications/{app_id}/role-groups
Request samples 
Response samples 
application/json
{
  • "result": [
    ]
}
Update role group
Update an existing role group for this application. 

Required permissions: organizations:edit, roles:edit.


SecurityOAuth2: AdminAccessToken 
Request 
path Parameters
app_id
required
string
ID of the application the group is in


 
group_id
required
string
ID of the group to set the roles to


 
Request Body schema: application/json
required
name
string
Name of the roles group


 
description
string
Description of the roles group


 
display_name
string
Group display name


 
role_ids
string
Ids of the roles


 
Responses 
404
409
put/v1/applications/{app_id}/role-groups/{group_id}
Request samples 
application/json
{
  • "name": "My Group",
  • "description": "My Group's description",
  • "display_name": "string",
  • "role_ids": [
    ]
}
Response samples 
application/json
{
  • "message": "string",
  • "error_code": 404
}
Delete role group
Delete role group. 

Required permissions: organizations:delete, roles:delete.


SecurityOAuth2: AdminAccessToken 
Request 
path Parameters
app_id
required
string
ID of the application the group is in


 
group_id
required
string
ID of the group to delete


 
Responses 
404
delete/v1/applications/{app_id}/role-groups/{group_id}
Request samples 
Response samples 
application/json
{
  • "message": "string",
  • "error_code": 404
}
Set role group's roles
Update the roles of an existing role group of your application. This will replace any existing set of roles of that group. 

Required permissions: organizations:edit, roles:edit.


SecurityOAuth2: AdminAccessToken 
Request 
path Parameters
app_id
required
string
ID of the application to set the roles to


 
group_id
required
string
ID of the group to set the roles to


 
Request Body schema: application/json
required
role_ids
required
Array of strings
Ids of the roles


 
Responses 
202
post/v1/applications/{app_id}/role-groups/{group_id}/roles/set
Request samples 
application/json
{
  • "role_ids": [
    ]
}