Roles and permissions

Understand the default roles Userverse creates automatically, and learn how to create, update, list, and delete custom roles for a company.

Every company in Userverse uses roles to control what members can do. This guide explains the default roles and walks through the full CRUD lifecycle for custom roles.

All role management endpoints require a valid JWT Bearer token. Unless stated otherwise, the authenticated user must have the Administrator role in the target company.

Default roles

When you create a company, Userverse automatically provisions two roles:

Role	Description
Administrator	Full access to manage users and data.
Viewer	Read-only access to company data.

Default roles (Administrator and Viewer) cannot be deleted. Attempting to delete either will return a validation error.

Create a role

Send a POST request to /company/{company_id}/role.

name · string · required

Unique name for the new role within the company.

description · string

Human-readable description of what the role allows.

curl --request POST \
  --url http://localhost:8000/company/42/role \
  --header "Authorization: Bearer <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Editor",
    "description": "Can create and update content but cannot manage users."
  }'

A successful response returns 201 Created with the new role.

data · object

Show properties

name · string

Role name.

description · string

Role description.

Update a role

Send a PATCH request to /company/{company_id}/role/{name}, where {name} is the current name of the role you want to update. Both fields are optional.

name · string

New name for the role.

description · string

Updated description.

curl --request PATCH \
  --url "http://localhost:8000/company/42/role/Editor" \
  --header "Authorization: Bearer <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "description": "Can create, update, and publish content."
  }'

A successful response returns 200 OK with the updated role record.

List roles

Send a GET request to /company/{company_id}/roles to retrieve a paginated list of all roles for a company.

curl --request GET \
  --url "http://localhost:8000/company/42/roles" \
  --header "Authorization: Bearer <your_access_token>"

You can filter and paginate results with optional query parameters:

Parameter	Type	Description
name	string	Filter by role name.
description	string	Filter by role description.

A successful response returns 200 OK with a paginated list of role records.

data · object

Show properties

records · array

List of role objects, each with name and description.

pagination · object

Pagination metadata including total record count, current page, and page size.

Delete a role

Send a DELETE request to /company/{company_id}/role. Because deleting a role would leave assigned members without a role, you must provide a replacement role — all users currently assigned the deleted role are automatically reassigned to it.

role_name_to_delete · string · required

Name of the role to delete. Cannot be Administrator or Viewer.

replacement_role_name · string · required

Name of an existing role to reassign affected users to.

curl --request DELETE \
  --url http://localhost:8000/company/42/role \
  --header "Authorization: Bearer <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "role_name_to_delete": "Editor",
    "replacement_role_name": "Viewer"
  }'

A successful response returns 200 OK confirming the role was deleted and members were reassigned.

Before deleting a role, use GET /company/{company_id}/users?role_name=Editor to see which users will be reassigned.

Related guides

Company management

Create companies and manage their members.

User management

Register, log in, and update user profiles.