Roles & Permissions

Configure role-based access control (RBAC) to manage what users and teams can do. Endpoints for roles, policies, and assignments plus the effective-permissions API.

Configure role-based access control (RBAC) to manage what users and teams can do.

Every organization has three built-in system roles: Viewer, Editor and Admin. System roles are marked isSystem: true and cannot be modified or deleted. Create custom roles for anything in between.

Roles

List Roles

GET/roles

List all roles in your organization.

Create Role

POST/roles

Create a new role with a set of policies.

Request · bash

curl -X POST https://api.zop.dev/roles \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Developer",
  "policies": [
    { "policyName": "resource:view", "allResources": true },
    { "policyName": "schedule:view", "allResources": true },
    { "policyName": "schedule:create", "allResources": true },
    { "policyName": "schedule:update", "allResources": true }
  ]
}'

Response · json

{
"data": {
  "id": "5b2c8e4a-1f3d-4a7b-9c6e-8d0f2a4b6c8e",
  "orgId": "3f6c2a9e-8b1d-4c7e-9f2a-1d5e6b7c8a90",
  "name": "Developer",
  "isSystem": false,
  "policies": [
    { "policyName": "resource:view", "allResources": true },
    { "policyName": "schedule:view", "allResources": true },
    { "policyName": "schedule:create", "allResources": true },
    { "policyName": "schedule:update", "allResources": true }
  ],
  "createdAt": "2025-02-20T14:00:00Z",
  "updatedAt": "2025-02-20T14:00:00Z"
}
}

To limit a policy to specific resources, set allResources to false and list the IDs in resourceIds (comma-separated).

Get Role

GET/roles/{roleID}

Get a role with its assigned policies.

Update Role

PUT/roles/{roleID}

Update a custom role's name or policies.

Delete Role

DELETE/roles/{roleID}

Delete a custom role. System roles cannot be deleted, and a role that is still assigned returns 409.

Policies

Policies are predefined permissions that can be assigned to roles. Each policy grants access to a specific action on a resource type.

List Policies

GET/roles/policies

List all available policies that can be assigned to roles.

Role Assignments

List Assignments

GET/assignments

List all role assignments in your organization.

Create Assignment

POST/assignments

Assign a role to a user or a team.

Request · bash

curl -X POST https://api.zop.dev/assignments \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "assigneeType": "user",
  "assigneeId": "engineer@company.com",
  "roleId": "5b2c8e4a-1f3d-4a7b-9c6e-8d0f2a4b6c8e"
}'

Response · json

{
"data": {
  "id": "8e6a4c2b-0d9f-4b7a-a5c3-1e2f3a4b5c6d",
  "orgId": "3f6c2a9e-8b1d-4c7e-9f2a-1d5e6b7c8a90",
  "assigneeType": "user",
  "assigneeId": "engineer@company.com",
  "roleId": "5b2c8e4a-1f3d-4a7b-9c6e-8d0f2a4b6c8e",
  "createdAt": "2025-02-20T14:30:00Z",
  "updatedAt": "2025-02-20T14:30:00Z"
}
}

Field	Description
`assigneeType`	`user` or `team`
`assigneeId`	The user's email, or the team ID
`roleId`	The role to grant
`policies`	Optional. Extra policies on the assignment; use `resourceIds` to scope them to specific resources

Update Assignment

PUT/assignments/{assignmentID}

Update a role assignment's role or policies.

Delete Assignment

DELETE/assignments/{assignmentID}

Remove a role assignment.

Checking Permissions

Get Current User Permissions

GET/permissions

Get the effective permissions for the currently authenticated user.

Get User Permissions

GET/users/{email}/permissions

Get the effective permissions for a specific user.

Verify Permission

GET/users/{email}/permissions/verify

Check whether a user has a specific permission.

Query parameters: ?policyName=schedule:update&resourceID=<resource id>. policyName is required; resourceID is optional.

Role Object

Field	Type	Description
`id`	string	Unique role ID
`orgId`	string	Organization ID
`name`	string	Role display name
`isSystem`	boolean	`true` for the built-in Viewer, Editor and Admin roles, which cannot be modified
`policies`	object[]	Policies on the role: `policyName`, `allResources`, and optional `resourceIds`
`metadata`	object	Optional extra data
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp