API Keys

API keys are scoped, revocable, and per-workspace. Format wp_live_<32 chars>. Send them as X-API-Key or as Authorization: Bearer wp_live_.... Both forms are accepted on every endpoint.

Scopes

Scope	Grants
`context:read`	`GET /v1/context/:id`, `GET /v1/context?email=`
`account:read`	`GET /v1/account/:id`
`memory:write`	`POST /v1/memory`
`events:write`	`POST /v1/events`
`keys:manage`	`GET/POST/DELETE /v1/keys`, `GET /v1/keys/whoami`

A key with no scopes is valid for whoami only. Most agents want context:read + memory:write. Ingest pipelines want events:write.

Issue a key

Dashboard

Settings > API Keys > Issue Key. Pick a name, check the scopes, copy the secret. The full secret is shown once.

CLI


wp keys issue --name "support agent" --scope context:read,memory:write

REST


curl https://api.waypath.app/v1/keys \
  -H "X-API-Key: wp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "support agent", "scopes": ["context:read", "memory:write"] }'


const res = await fetch('https://api.waypath.app/v1/keys', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WAYPATH_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'support agent',
    scopes: ['context:read', 'memory:write'],
  }),
})
const { key } = await res.json()


import os, requests
res = requests.post(
    'https://api.waypath.app/v1/keys',
    headers={'X-API-Key': os.environ['WAYPATH_API_KEY']},
    json={'name': 'support agent', 'scopes': ['context:read', 'memory:write']},
).json()

Response


{
  "id": "key_91ab2c",
  "key": "wp_live_8a1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q",
  "prefix": "wp_live_8a1c",
  "name": "support agent",
  "scopes": ["context:read", "memory:write"],
  "created_at": "2026-04-29T18:00:00Z"
}

key is the full secret. It is returned ONCE on issue and never again. Subsequent GET /v1/keys calls return only prefix.

List keys


curl https://api.waypath.app/v1/keys -H "X-API-Key: wp_live_..."

Revoke a key


curl -X DELETE https://api.waypath.app/v1/keys/key_91ab2c \
  -H "X-API-Key: wp_live_..."

wp keys revoke key_91ab2c does the same. Revocation is immediate.

Resolve the calling key


curl https://api.waypath.app/v1/keys/whoami -H "X-API-Key: wp_live_..."

Returns workspace ID, key ID, prefix, and scopes. Useful for sanity checks in CI and for prompts like “which workspace am I writing to”.

Rotation

There is no built-in rotation endpoint. The pattern is: issue a new key, redeploy with the new key, revoke the old key. Keep the overlap window short.

Errors

Status	Code	Cause
400	invalid_payload	Missing `name` or `scopes`.
401	unauthenticated	Missing or invalid X-API-Key.
403	forbidden_scope	Caller lacks `keys:manage`.
404	not_found	Key ID not in this workspace.
429	rate_limited	Per-workspace cap on key issue (10 / hour).