> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Members & roles

> Manage organization members, roles, and permission scopes

Organizations use role-based access control. Members are assigned roles, and roles contain scopes that grant specific permissions.

## Members

### Add member

```bash theme={null}
POST /api/organizations/{id}/members
```

| Parameter | Type | Required | Description                         |
| --------- | ---- | -------- | ----------------------------------- |
| `email`   | body | Yes      | User's email address                |
| `role_id` | body | No       | Role to assign (defaults to Member) |

If the user doesn't have a platform account, they receive an invitation email.

**Authentication:** Organization member + `members:invite` scope.

### Update member role

```bash theme={null}
PUT /api/organizations/{id}/members/{userId}/role
```

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `role_id` | body | Yes      | New role ID |

**Authentication:** Organization member + `members:manage_roles` scope.

### Remove member

```bash theme={null}
DELETE /api/organizations/{id}/members/{userId}
```

Members can remove themselves. Removing other members requires the `members:remove` scope.

**Authentication:** Organization member + `members:remove` scope (or self-removal).

## Roles

Every organization starts with two default roles:

| Role   | Description                                    |
| ------ | ---------------------------------------------- |
| Admin  | All scopes assigned — full organization access |
| Member | No scopes — basic authenticated access         |

### List roles

```bash theme={null}
GET /api/organizations/{id}/roles
```

Returns all roles with their assigned scopes.

**Authentication:** Organization member required.

### Create role

```bash theme={null}
POST /api/organizations/{id}/roles
```

| Parameter   | Type | Required | Description                  |
| ----------- | ---- | -------- | ---------------------------- |
| `name`      | body | Yes      | Role display name            |
| `scope_ids` | body | No       | Array of scope IDs to assign |

**Authentication:** Organization member + `members:manage_roles` scope.

### Get role

```bash theme={null}
GET /api/organizations/{id}/roles/{roleId}
```

**Authentication:** Organization member + `members:manage_roles` scope.

### Update role

```bash theme={null}
PATCH /api/organizations/{id}/roles/{roleId}
```

| Parameter   | Type | Description               |
| ----------- | ---- | ------------------------- |
| `name`      | body | Updated role name         |
| `scope_ids` | body | Updated scope assignments |

**Authentication:** Organization member + `members:manage_roles` scope.

### Delete role

```bash theme={null}
DELETE /api/organizations/{id}/roles/{roleId}
```

Cannot delete the default Admin role. Members assigned to the deleted role should be reassigned first.

**Authentication:** Organization member + `members:manage_roles` scope.

## Scopes

### List assignable scopes

```bash theme={null}
GET /api/scopes
```

Returns scopes that can be assigned to organization roles.

**Authentication:** User authentication required.

### Get scope

```bash theme={null}
GET /api/scopes/{id}
```

**Authentication:** User authentication required.

## User invitations

### Invite user

```bash theme={null}
POST /api/users/invite
```

| Parameter | Type | Required | Description                        |
| --------- | ---- | -------- | ---------------------------------- |
| `email`   | body | Yes      | User's email address               |
| `orgId`   | body | No       | Organization to add the user to    |
| `roleId`  | body | No       | Role to assign in the organization |

If `orgId` is provided, the user is invited to the platform and added to the organization in one step.

**Authentication:** Organization member + `members:invite` scope.