# 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.

Source: https://zop.dev/developer-docs/administration/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.

```bash title="Request"
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"
    ]
  }'
```

```json title="Response"
{
  "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.

**Info**

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.

```bash title="Request"
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"
  }'
```

```json title="Response"
{
  "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

### Delete Assignment

### DELETE /assignments/{assignmentID}

Remove a role assignment.

## Checking Permissions

**Tip**

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 |