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

Response

{
  "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

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

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

{
  "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

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

Node.js

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

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

Examples

curl

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

Node.js

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

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

Examples

curl

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