Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SoftwareVerse/userverse/llms.txt

Use this file to discover all available pages before exploring further.

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:
RoleDescription
AdministratorFull access to manage users and data.
ViewerRead-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

​
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:
ParameterTypeDescription
namestringFilter by role name.
descriptionstringFilter by role description.
A successful response returns 200 OK with a paginated list of role records.
​
data
object

​
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.

Company management

Create companies and manage their members.

User management

Register, log in, and update user profiles.

Build docs developers (and LLMs) love

Get started for freeTalk to us