Roles

Roles define access permissions and limitations for users within an account. They allow you to manage what actions users can perform with resources, such as creating or managing threads. An account can have multiple roles, and users can be assigned to these roles based on their responsibilities.

Role object

Attributes

id

String

A unique identifier assigned to the role.

name

String

The display name of the role.

slug

String

A human-friendly identifier for the role.

description

String

A short description explaining the purpose of the role.

isDefault

Boolean

Specifies whether this role is a default role for the account.

permissions

Array

A list of permissions that define what actions users assigned this role can perform.

created_at

Date

The date and time when the role was created.

updated_at

Date

The date and time when the role was last updated.

{
  "id": "role_042bfERm4MnhPhBhP7SY",
  "name": "Standard Role",
  "slug": "standard-role",
  "description": "This is the default standard role assigned to new users.",
  "isDefault": true,
  "permissions": [
    "thread_create",
    "thread_read"
  ],
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-01T00:00:00.000Z"
}

List roles

Retrieve a list of all roles defined for the account, including their details and permissions.

GEThttps://api.metorial.com/roles
curl -X GET https://api.metorial.com/roles 
  -H "Authorization: Bearer metorial_sk_..."

Get role

Fetch detailed information about a specific role by its unique identifier.

URL Parameters

roleId

String

The unique identifier of the role.

GEThttps://api.metorial.com/roles/:roleId
curl -X GET "https://api.metorial.com/roles/role_Rm4Mnheq2bfEPhBhP7SY" 
  -H "Authorization: Bearer metorial_sk_..."

Create role

Create a new role with specific permissions and details.

Request Body

name

String

The display name of the new role.

slug

String

A URL-friendly identifier for the new role.

description

StringOptional

An optional short description of the role.

permissions

Array

A list of permissions assigned to the new role.

POSThttps://api.metorial.com/roles
curl -X POST https://api.metorial.com/roles 
  -H "Authorization: Bearer metorial_sk_..." 
  -H "Content-Type: application/json" 
  -d '{
    "name": "New Role",
    "slug": "new-role",
    "description": "This is a new role.",
    "permissions": ["thread_create", "thread_read"],
  }'

Update role

Modify the details and permissions of an existing role.

URL Parameters

roleId

String

The unique identifier of the role.

Request Body

name

String

The updated display name of the role.

slug

String

The updated URL-friendly identifier for the role.

description

StringOptional

An optional updated description of the role.

permissions

Array

The updated list of permissions for the role.

PUThttps://api.metorial.com/roles/:roleId
curl -X POST https://api.metorial.com/roles/role_Rm4Mnheq2bfEPhBhP7SY 
  -H "Authorization: Bearer metorial_sk_..." 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Updated Role",
    "slug": "updated-role",
    "description": "This role has been updated.",
    "permissions": ["thread_create", "thread_read"],
  }'