Skip to main content
Roles enable you to implement Role-Based Access Control (RBAC) in your applications. Use this resource to create, retrieve, update, and delete roles, as well as manage role permissions and user assignments.

​
Methods

​
List Roles

Retrieve detailed list of user roles created in your tenant. 
func (c *Client) List(
    ctx context.Context,
    request *management.ListRolesRequestParameters,
    opts ...option.RequestOption,
) (*core.Page[*int, *management.Role, *management.ListRolesOffsetPaginatedResponseContent], error)
​
request
*management.ListRolesRequestParameters
Query parameters for filtering and pagination
​
Role
*management.Role

​
Example

ctx := context.Background()

listRequest := &management.ListRolesRequestParameters{
    PerPage: management.Int(25),
}

rolesPage, err := mgmt.Roles.List(ctx, listRequest)
if err != nil {
    log.Fatalf("Error listing roles: %v", err)
}

// Iterate through all roles
iterator := rolesPage.Iterator()
for iterator.Next(ctx) {
    role := iterator.Current()
    fmt.Printf("Role: %s - %s\n", 
        role.GetName(), 
        role.GetDescription(),
    )
}

if iterator.Err() != nil {
    log.Fatalf("Error iterating roles: %v", iterator.Err())
}
The returned list does not include standard roles available for tenant members, such as Admin or Support Access.

​
Create Role

Create a user role for Role-Based Access Control. 
func (c *Client) Create(
    ctx context.Context,
    request *management.CreateRoleRequestContent,
    opts ...option.RequestOption,
) (*management.CreateRoleResponseContent, error)
​
request
*management.CreateRoleRequestContent
required

​
Example

createRequest := &management.CreateRoleRequestContent{
    Name:        "Content Editor",
    Description: management.String("Can create and edit content"),
}

role, err := mgmt.Roles.Create(ctx, createRequest)
if err != nil {
    log.Fatalf("Error creating role: %v", err)
}

fmt.Printf("Created role: %s (ID: %s)\n", role.GetName(), role.GetID())
New roles are not associated with any permissions by default. Use the Permissions nested resource to assign permissions after creating a role.

​
Get Role

Retrieve details about a specific user role specified by ID. 
func (c *Client) Get(
    ctx context.Context,
    id string,
    opts ...option.RequestOption,
) (*management.GetRoleResponseContent, error)
​
id
string
required
ID of the role to retrieve

​
Example

role, err := mgmt.Roles.Get(ctx, "rol_abc123")
if err != nil {
    log.Fatalf("Error retrieving role: %v", err)
}

fmt.Printf("Role: %s\n", role.GetName())
fmt.Printf("Description: %s\n", role.GetDescription())

​
Update Role

Modify the details of a specific user role specified by ID. 
func (c *Client) Update(
    ctx context.Context,
    id string,
    request *management.UpdateRoleRequestContent,
    opts ...option.RequestOption,
) (*management.UpdateRoleResponseContent, error)
​
id
string
required
ID of the role to update
​
request
*management.UpdateRoleRequestContent
required

​
Example

updateRequest := &management.UpdateRoleRequestContent{
    Description: management.String("Can create, edit, and publish content"),
}

updatedRole, err := mgmt.Roles.Update(ctx, "rol_abc123", updateRequest)
if err != nil {
    log.Fatalf("Error updating role: %v", err)
}

fmt.Printf("Updated role: %s\n", updatedRole.GetName())

​
Delete Role

Delete a specific user role from your tenant. 
func (c *Client) Delete(
    ctx context.Context,
    id string,
    opts ...option.RequestOption,
) error
​
id
string
required
ID of the role to delete

​
Example

err := mgmt.Roles.Delete(ctx, "rol_abc123")
if err != nil {
    log.Fatalf("Error deleting role: %v", err)
}

fmt.Println("Role deleted successfully")
Once deleted, the role is removed from any user who was previously assigned that role. This action cannot be undone.

​
Nested Resources

The Roles client provides access to nested resources:

​
Permissions

Manage permissions associated with roles: 
// Assign permissions to a role
mgmt.Roles.Permissions.Add(ctx, roleID, permissionsRequest)

// List permissions for a role
mgmt.Roles.Permissions.List(ctx, roleID, listRequest)

// Remove permissions from a role
mgmt.Roles.Permissions.Delete(ctx, roleID, permissionsRequest)

​
Users

Manage users assigned to roles: 
// Assign users to a role
mgmt.Roles.Users.Add(ctx, roleID, usersRequest)

// List users assigned to a role
mgmt.Roles.Users.List(ctx, roleID, listRequest)

// Remove users from a role
mgmt.Roles.Users.Delete(ctx, roleID, usersRequest)

​
Best Practices

Role Design

Design roles based on job functions rather than individual users. This makes role management more scalable and maintainable.

Principle of Least Privilege

Assign only the minimum permissions necessary for a role to perform its function. This minimizes security risks.

Role Naming

Use clear, descriptive names for roles that reflect their purpose. Avoid technical jargon that may confuse administrators.

Build docs developers (and LLMs) love

Get started for freeTalk to us