Roles are your workspace's permission sets. Every staff user holds one role, and each role grants keys from the permission catalog, the same keys your Workspace Admin grants to API integrations. Use this read-only list to audit who can do what, or to mirror roles in an identity system.
All endpoints sit under /api/v1 and need an API key (Authorization: Bearer jdr_live_…) created by your Workspace Admin in Settings → Integrations.
Endpoints
| Method and path | What it does | Permission |
|---|---|---|
GET /api/v1/roles | List roles with their permission keys (cursor pagination, updatedSince) | users.view |
Roles are read-only through the API. Create and edit them in Settings → Users → Roles.
The role object
| Field | Type | Notes |
|---|---|---|
id | string | Matches role.id on a user. |
name | object | { ar, en }. |
description | string or null | |
systemKey | string or null | Set on the built-in roles: workspace_admin in every workspace, plus the original preset roles in workspaces created before roles became admin-built. Null on roles your admins created. |
isWorkspaceAdmin | boolean | The locked Workspace Admin role: it holds every permission and can't be edited. |
dataScope | string | WORKSPACE (all records) or REPORTING_LINE (the holder's reporting line only). |
permissions | array | Catalog keys as granted, e.g. recruitment.act, audit.view. The Workspace Admin role lists every key. <module>.act implies <module>.view. |
createdAt, updatedAt | ISO 8601 |
Webhook events
| Event | When | data.object |
|---|---|---|
role.created | A role is created | The role |
role.updated | Its name, description, data scope or permissions change (changedFields) | The role |
role.deleted | A role is deleted (only roles nobody holds can be) | { id, externalRefs: [] } |
A permission change also moves the role's updatedAt, so updatedSince picks it up. Deleted roles are listed in the deletion feed (GET /api/v1/deleted).
Errors
| Status and code | Meaning |
|---|---|
403 forbidden | The key lacks users.view. |
422 validation_failed | Invalid limit, cursor or updatedSince. |
Example
curl "https://jadiroon.com/api/v1/roles?limit=1" -H "Authorization: Bearer $JADIROON_KEY"
{
"data": [
{
"id": "cmviqdaf8004lknffw1rpf3ww",
"name": { "ar": "مدير مساحة العمل", "en": "Workspace Admin" },
"description": null,
"systemKey": "workspace_admin",
"isWorkspaceAdmin": true,
"dataScope": "WORKSPACE",
"permissions": ["planning.view", "planning.act", "…", "audit.view", "audit.export"],
"createdAt": "2026-10-21T22:06:41.011Z",
"updatedAt": "2026-10-21T22:06:41.011Z"
}
],
"nextCursor": "Y212aXFkYWY4MDA0bGtuZmZ3MXJwZjN3dw"
}