Roles & Permissions

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

Roles

List Roles

GET

/roles

List all roles in your organization.

Create Role

POST

/roles

Create a new role with a set of policies.

Requestbash

curl -X POST https://zopnight.com/api/roles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Developer",
    "description": "Can view resources and manage schedules",
    "policies": [
      "resources:read",
      "schedules:read",
      "schedules:write"
    ]
  }'

Responsejson

{
  "data": {
    "id": "role_dev456",
    "name": "Developer",
    "description": "Can view resources and manage schedules",
    "policies": [
      "resources:read",
      "schedules:read",
      "schedules:write"
    ],
    "createdBy": "admin@company.com",
    "createdAt": "2025-02-20T14:00:00Z",
    "updatedAt": "2025-02-20T14:00:00Z"
  }
}

Get Role

GET

/roles/{roleID}

Get a role with its assigned policies.

Update Role

PUT

/roles/{roleID}

Update role name, description, or policies.

Delete Role

DELETE

/roles/{roleID}

Delete a role. Existing assignments using this role are removed.

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

/policies

List all available policies that can be assigned to roles.

Policy Format

Policies follow the format resource:action. For example, schedules:write grants the ability to create, update, and delete schedules.

Role Assignments

List Assignments

GET

/assignments

List all role assignments in your organization.

Create Assignment

POST

/assignments

Assign a role to a user, optionally scoped to a team or resource.

Requestbash

curl -X POST https://zopnight.com/api/assignments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "engineer@company.com",
    "roleID": "role_dev456",
    "scope": "team:team_abc123"
  }'

Responsejson

{
  "data": {
    "id": "asgn_789xyz",
    "email": "engineer@company.com",
    "roleID": "role_dev456",
    "scope": "team:team_abc123",
    "createdBy": "admin@company.com",
    "createdAt": "2025-02-20T14:30:00Z",
    "updatedAt": "2025-02-20T14:30:00Z"
  }
}

Update Assignment

PUT

/assignments/{assignmentID}

Update a role assignment's role or scope.

Delete Assignment

DELETE

/assignments/{assignmentID}

Remove a role assignment.

Checking Permissions

Permission Resolution

Effective permissions are computed from all role assignments for a user, including org-wide roles and team-scoped roles. More specific scopes take precedence.

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. Pass action and resource as query parameters.

Query parameters: ?action=write&resource=schedules

Role Object

Field	Type	Description
`id`	string	Unique role ID
`name`	string	Role display name
`description`	string	Optional description
`policies`	string[]	List of policy identifiers assigned to the role
`createdBy`	string	Email of the creator
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp