API Keys

Agent keys are workspace-bound, scoped, revocable, rate-limited, and prefixed with wp_live_. Send them as either:

Authorization: Bearer wp_live_...

or:

X-API-Key: wp_live_...

Both forms are accepted by the capability gateway, CLI, and MCP surfaces.

01What a key controls

Each key has four permission layers:

Optional controls:

Capability grants may be concrete ids (context.get), full grant strings (capability:context.get), or *.

02Recommended grants

Start narrow and expand only when the agent needs more capability:

Use dry_run and queue first. Add execute only when the key, workspace policy, quota, idempotency, and AOS approval model are ready for it.

03Issue a key

Dashboard

Settings > API Keys > Issue Key. Pick a name, agent label, legacy scopes, capability grants, allowed modes, rate limit, and optional quota override. Copy the secret. The full secret is shown once.

CLI

wp keys issue "cursor-agent" \
  --agent cursor \
  --scope v1:context:read v1:capabilities:invoke \
  --grant capability:context.get capability:memory.write \
  --mode dry_run execute

Key management requires a dashboard/JWT-authenticated context. A wp_live_... agent key cannot mint, list, or revoke other keys.

REST

curl https://api.waypath.app/api/v1/keys \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cursor-agent",
    "agent": "cursor",
    "scopes": ["v1:context:read", "v1:capabilities:invoke"],
    "grants": ["capability:context.get", "capability:memory.write"],
    "allowed_modes": ["dry_run", "execute"],
    "auto_run": false,
    "rate_limit_per_min": 300,
    "quota_override_monthly": 250
  }'

04Issue response

{
  "id": "key_91ab2c",
  "key": "wp_live_8a1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q",
  "prefix_preview": "8a1c2d3e",
  "name": "cursor-agent",
  "agent": "cursor",
  "scopes": ["v1:context:read", "v1:capabilities:invoke"],
  "grants": ["capability:context.get", "capability:memory.write"],
  "allowed_modes": ["dry_run", "execute"],
  "auto_run": false,
  "quota_override_monthly": 250,
  "rate_limit_per_min": 300,
  "created_at": "2026-06-28T18:00:00Z"
}

key is the full secret. It is returned once and cannot be recovered later. List responses return only metadata and previews.

05List keys

curl https://api.waypath.app/api/v1/keys \
  -H "Authorization: Bearer <dashboard-jwt>"

Returns key metadata including grants, allowed modes, auto_run, quota override, last used timestamp, and revoked state.

06Revoke a key

curl -X DELETE https://api.waypath.app/api/v1/keys/key_91ab2c \
  -H "Authorization: Bearer <dashboard-jwt>"

Revocation is immediate. Revoked keys fail on capability routes, MCP, CLI, and whoami.

07Resolve the calling key

curl https://api.waypath.app/api/v1/keys/whoami \
  -H "Authorization: Bearer wp_live_..."

Response:

{
  "id": "key_91ab2c",
  "workspace_id": "ws_123",
  "agent": "cursor",
  "name": "cursor-agent",
  "scopes": ["v1:context:read", "v1:capabilities:invoke"],
  "grants": ["capability:context.get"],
  "allowed_modes": ["dry_run", "execute"],
  "auto_run": false,
  "quota_override_monthly": 250,
  "revoked_at": null,
  "rate_limit_per_min": 300,
  "created_at": "2026-06-28T18:00:00Z",
  "last_used_at": "2026-06-28T18:01:00Z"
}

whoami also returns rate-limit headers.

08Errors

09See also

• Quickstart
• Capabilities
• MCP Setup
• CLI