Roles

A role is a named collection of permissions. Instead of assigning individual permissions to every user, you group them into a role and assign that role to users.

What Is a Role?

Roles make permission management practical. Without roles, you would need to assign each permission individually to every user — a maintenance nightmare as your application grows.

With roles:

You define a role (e.g., store-manager, inventory-staff).
You assign permissions to that role.
You assign that role to users.

When you change the permissions of a role, those changes apply immediately to all users with that role — no need to update users one by one.

Example Roles

Here is an example of how roles might be structured for a business application:

    graph TD
    SM["Store Manager"] --> P1["products:create"]
    SM --> P2["products:read"]
    SM --> P3["products:update"]
    SM --> P4["products:delete"]
    SM --> P5["orders:create"]
    SM --> P6["orders:read"]
    SM --> P7["users:read"]

    IS["Inventory Staff"] --> P2
    IS --> P3
    IS --> P6

Role	Code	Description	Permissions
Store Manager	`store-manager`	Manages store operations including products, orders, and staff	`products:create`, `products:read`, `products:update`, `products:delete`, `orders:read`, `orders:update`, `users:read`
Inventory Staff	`inventory-staff`	Manages product inventory and stock levels	`products:read`, `products:update`, `orders:read`

Creating a Role

You can create a role using the following API. Here we create the Store Manager role:

curl --request POST \
  --url https://auth.roled.id/api/v1/projects/2JUSLUee46xG6iEwG8JwPc/roles \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "store-manager",
    "name": "Store Manager",
    "description": "Manages store operations including products, orders, and staff",
    "permission_ids": [
      "2JUUyotLUqz5eqsuYXXDet",
      "2JUUyotLUr7SuBqkzjRbTc",
      "2JUUyotLUrApxL7zcx7Xoy",
      "2JUUyotLUrDfBK9iwe25jj",
      "2JRjbZKS7f4oRkDaAD4gAF",
      "2JRjbZKS7fJAfNjgShH3TE",
      "2JRjbZKS7h72qSpPAJBuSj"
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "id": "2JRtjyxfZudzaJkFczgoUY",
    "created_at": "2026-07-16T14:30:00Z",
    "updated_at": "2026-07-29T08:30:00Z",
    "code": "store-manager",
    "name": "Store Manager",
    "description": "Manages store operations including products, orders, and staff",
    "permissions": [
      {
        "id": "2JUUyotLUqz5eqsuYXXDet",
        "resource_name": "Products",
        "permission_name": "Create"
      },
      {
        "id": "2JUUyotLUr7SuBqkzjRbTc",
        "resource_name": "Products",
        "permission_name": "Read"
      },
      {
        "id": "2JUUyotLUrApxL7zcx7Xoy",
        "resource_name": "Products",
        "permission_name": "Update"
      },
      {
        "id": "2JUUyotLUrDfBK9iwe25jj",
        "resource_name": "Products",
        "permission_name": "Delete"
      },
      {
        "id": "2JRjbZKS7f4oRkDaAD4gAF",
        "resource_name": "Orders",
        "permission_name": "Read"
      },
      {
        "id": "2JRjbZKS7fJAfNjgShH3TE",
        "resource_name": "Orders",
        "permission_name": "Update"
      },
      {
        "id": "2JRjbZKS7h72qSpPAJBuSj",
        "resource_name": "Users",
        "permission_name": "Read"
      }
    ]
  }
}

Assigning a Role to a User

A user can have one role at a time. You can assign or change a user’s role by calling an edit user API with the new role_id in request body. For example, assigning the Store Manager role to Alice Smith:

curl --request PUT \
  --url https://auth.roled.id/api/v1/projects/2JUSLUee46xG6iEwG8JwPc/users/2JRtk7i2aEFKpsKTNx6YWR \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "Alice Smith",
    "avatar_url": "https://example.com/profiles/alice-smith.jpg",
    "email": "alice.smith@example.com",
    "role_id": "2JRtjyxfZudzaJkFczgoUY",
    "is_active": true
  }'

Listing All Roles in a Project

You can fetch all roles in a project when assigning to users:

curl --request GET \
  --url https://auth.roled.id/api/v1/projects/2JUSLUee46xG6iEwG8JwPc/roles \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...'

How Roles Differ from Client Permissions

	Users (via Roles)	Clients
Permission model	Assigned via a role	Assigned directly
Multiple permissions	Yes, via the role	Yes, directly
Change impact	All users with role affected	Only that client affected

Clients do not use roles — their permissions are assigned directly. See Clients for details.

Key Points

Roles group permissions together to make management easier.
A user has one role at a time.
Changing a role’s permissions immediately affects all users with that role.
Roles are scoped to a single project.

Users Resources & Permissions