List Roles

Retrieve a paginated list of roles defined in a project.

Endpoint

/api/v1/projects/{project_id}/roles

Method

GET

Path Parameters

Parameter	Type	Required	Description
`project_id`	`string`	Yes	Unique ID of the project

Headers

Header	Required	Description
`Authorization`	Yes	Bearer access token: `Bearer <access_token>`

Query Parameters

Parameter	Type	Required	Description
`page_num`	`integer`	No	Page number (default: 1)
`page_size`	`integer`	No	Results per page (default: 10)
`sort_by`	`string`	No	Field name to sort by. Option: `created_at` (default) `updated_at` `name` `code`
`sort_dir`	`string`	No	Sort direction. Option: `asc` `desc` (default)
`search`	`string`	No	Search keyword for role code, name, or description

Required Permission

roles:read

Examples

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

{
  "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"
    },
    {
      "id": "2JRYtvorEzhNgMLHeqZiNo",
      "created_at": "2026-07-16T14:30:00Z",
      "updated_at": "2026-07-29T08:30:00Z",
      "code": "inventory-staff",
      "name": "Inventory Staff",
      "description": "Manages product inventory and stock levels"
    }
  ],
  "pagination": {
    "page_num": 1,
    "page_size": 2,
    "total_data": 2
  }
}

Error Codes

Code	HTTP Status	Description
`invalid_authorization_token`	401	Missing or invalid authorization token
`insufficient_permission`	403	Insufficient permission
`project_not_found`	404	Project not found
`system_error`	500	Internal server error

Roles Get Role Details