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

# Policy Routes

> Role management and user access resolution.

<Snippet file="stub-warning.mdx" />

## List roles

```
GET /api/policy/roles
```

**Response (200):**

```json theme={null}
{
  "roles": []
}
```

***

## Create role

```
POST /api/policy/roles
```

### Request body

```json theme={null}
{
  "id": "developer",
  "name": "Developer",
  "patterns": ["github.**", "linear.issues.*", "slack.channels.list"]
}
```

Validated against `RoleSchema` from `@toolshed/shared`.

### Response (201)

```json theme={null}
{
  "created": {
    "id": "developer",
    "name": "Developer",
    "patterns": ["github.**", "linear.issues.*", "slack.channels.list"]
  }
}
```

<Note>The response wraps the role object in a `created` field.</Note>

***

## Update role

```
PUT /api/policy/roles/:id
```

| Parameter | In   | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | path | Yes      | Role ID     |

### Request body

Same shape as create -- a full `Role` object.

### Response (200)

```json theme={null}
{
  "updated": {
    "id": "developer",
    "name": "Developer",
    "patterns": ["github.**", "linear.**", "slack.**"]
  }
}
```

<Note>The response wraps the role object in an `updated` field. The `id` is taken from the URL path parameter.</Note>

***

## Resolve user tools

```
GET /api/policy/resolve?userId=<userId>
```

Returns the effective set of tools a user can access based on their role.

| Parameter | In    | Required | Description |
| --------- | ----- | -------- | ----------- |
| `userId`  | query | Yes      | User ID     |

**Response (200):**

```json theme={null}
{
  "userId": "user-123",
  "tools": []
}
```