# Permissions

Permission requests control which scopes a machine can access. Use these endpoints to list, inspect, revoke, and revalidate permissions.

## List Permissions

### GET `/api/permissions`

List all permission requests for the authenticated user. Can optionally filter by machine.

### Authentication

API key, Session cookie, or Machine JWT

### Query Parameters

| Name      | Type   | Description                           |
|-----------|--------|---------------------------------------|
| machineId | string | Filter permissions by a specific machine ID |

### Response

```json
{
  "permissions": [
    {
      "id": "pr_a1b2c3",
      "name": "github-access",
      "machineId": "m_8f3a...",
      "userId": "user_abc123",
      "status": "active",
      "mode": "scoped",
      "requestedScopes": ["github::repo"],
      "scopeApprovals": { "github::repo": "2026-02-10T..." },
      "createdAt": "2026-02-10T08:00:00.000Z",
      "allowDelegation": true
    }
  ]
}
```

### Examples

#### curl

```bash
curl https://keychains.dev/api/permissions \
  -H "Authorization: Bearer kc_your_api_key"

# Filter by machine
curl "https://keychains.dev/api/permissions?machineId=m_8f3a..." \
  -H "Authorization: Bearer kc_your_api_key"
```

#### Node.js

```javascript
const res = await fetch("https://keychains.dev/api/permissions", {
  headers: { Authorization: "Bearer kc_your_api_key" },
});
const { permissions } = await res.json();
```

## Get Specific Permission

### GET `/api/permissions/:id`

Get details of a specific permission request.

### Authentication

API key, Session cookie, or Machine JWT

### Response

```json
{
  "id": "pr_a1b2c3",
  "name": "github-access",
  "machineId": "m_8f3a...",
  "userId": "user_abc123",
  "status": "active",
  "mode": "scoped",
  "requestedScopes": ["github::repo"],
  "scopeApprovals": { "github::repo": "2026-02-10T..." },
  "createdAt": "2026-02-10T08:00:00.000Z",
  "allowDelegation": true,
  "description": "Access to GitHub repositories"
}
```

### Examples

#### curl

```bash
curl https://keychains.dev/api/permissions/pr_a1b2c3 \
  -H "Authorization: Bearer kc_your_api_key"
```

#### Node.js

```javascript
const res = await fetch("https://keychains.dev/api/permissions/pr_a1b2c3", {
  headers: { Authorization: "Bearer kc_your_api_key" },
});
const permission = await res.json();
```

## Revoke Permission

### DELETE `/api/permissions/:id`

Revoke a permission request. This immediately disables the permission and cascades to all delegates created from it.

### Authentication

API key, Session cookie, or Machine JWT

### Response

```json
{
  "id": "pr_a1b2c3",
  "status": "revoked",
  "revokedAt": "2026-02-17T10:00:00.000Z"
}
```

### Examples

#### curl

```bash
curl -X DELETE https://keychains.dev/api/permissions/pr_a1b2c3 \
  -H "Authorization: Bearer kc_your_api_key"
```

#### Node.js

```javascript
await fetch("https://keychains.dev/api/permissions/pr_a1b2c3", {
  method: "DELETE",
  headers: { Authorization: "Bearer kc_your_api_key" },
});
```

## Revalidate Permission

### POST `/api/permissions/:id/revalidate`

Trigger revalidation for a permission. Sets the status to 'needs_revalidation', freezing the permission until the user re-confirms. Useful for periodic security reviews.

### Authentication

Session cookie only (not API key — requires full user session)

### Response

```json
{
  "id": "pr_a1b2c3",
  "status": "needs_revalidation"
}
```

### Examples

#### curl

```bash
curl -X POST https://keychains.dev/api/permissions/pr_a1b2c3/revalidate \
  -H "Authorization: Bearer <session-jwt>"
```