Skip to content

API keys

Create, list, update, and revoke live and test API keys from the dashboard, each scoped to its own rate limit and environment.

Manage your API keys from the dashboard.

Note

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.

Request
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

Note

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.