Roles & Permissions | ZopDev Developer Docs

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.

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 }
    ]
  }'

{
  "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.

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"
  }'

{
  "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