API keys

Manage your API keys from the dashboard. These endpoints authenticate with your dashboard login session (a JWT access token), not a pm_ bearer key, which distinguishes them from the verification endpoints described in Authentication.

Create a key

POST /api/keys generates a new key and returns the raw secret once, in the raw_key field. Only its hash is stored, so save it immediately.

curl -X POST https://api.pricklymails.com/api/keys \
  -H "Authorization: Bearer your_jwt_access_token" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production server", "environment": "live" }'

Optionally pass scopes and enabled_checks to narrow what the key can do; both default to the project defaults when omitted. The rate limit is not accepted here: it is seeded from your plan and cannot be self-granted.

List and fetch

GET /api/keys lists every key you own, newest first. GET /api/keys/{uuid} fetches one, scoped to your account.

Update a key

PATCH /api/keys/{uuid} updates the display name or enabled_checks. Unset fields keep their current value. A requested check your plan does not allow returns 403. The rate limit is never editable through this endpoint: it is plan-driven and re-aligned automatically whenever your plan changes.

Revoke a key

DELETE /api/keys/{uuid} revokes the key. It is idempotent: revoking an already-revoked key returns the same row with its existing revoked_at timestamp.

Introspect the current key

GET /api/keys/me differs from the rest of this page: it authenticates with the pm_ bearer key itself, not a JWT, so an integration can confirm a freshly issued key resolves, and read its name, environment, scopes, and enabled checks, before running a billable verification.

Live vs test

A key's environment (live or test) is chosen at creation and is behavioral, not just a label: a pm_test_ key runs the sandbox described in Authentication and never bills your wallet.