Authentication

Send your key in the Authorization header. Nothing else authenticates a request.

Docs menu

Header

Authorization: Bearer $PRESSPROVE_API_KEY

A key goes in the header only. A cookie, a query parameter or HTTP Basic does not work, and a key in a URL is refused as no key.

Keys

A key is pp_test_ or pp_live_ followed by 43 letters and digits. Make and revoke keys in the console under Keys; there is no endpoint that makes a key, so a leaked key cannot make another.

  • We show a key once, when you make it. We keep only a fingerprint, so we cannot show it again. If you lose it, revoke it and make a new one.
  • Revoking is immediate. The next request with that key answers api_key_revoked.
  • Each key has a name and scopes, and the console shows when it was last used.
  • An account can hold 5 test keys. In live mode it can hold 5 keys, and 10 after the first paid top-up.

Test and live

KeyWhat it does
pp_test_Returns sample answers from a documented table. Fetches no page, charges nothing, writes no ledger entry. Works now.
pp_live_Fetches the real page and charges your balance. Available when live mode is open for your account.

A test key sees only test objects and a live key only live objects. An id from the other mode answers not_found. Every object says livemode. See Test mode.

Scopes

A key can do only what its scopes allow. A request outside them answers missing_scope.

ScopeAllowsEndpoints
readRead anything of the account: checks, monitors, reports, releases, balance, usage, ledger, events.16
checks:writeCreate and cancel checks.2
monitors:writeCreate, pause, resume, end and run monitors.5
reports:writeCreate proof reports.2
releases:writeOrder and approve paid press releases. Off by default; you switch it on for a key.3

Replace a key

  1. Make a new key with the same scopes.
  2. Put it in your software and deploy.
  3. Check under Keys that the old key was last used before the deploy.
  4. Revoke the old key.

Keep keys out of browsers

If a key may have leaked, revoke it in the console first, then look at the request log for use you do not recognize.

When the key is wrong

The answer is 401 with one of three codes, or 403 when the key is fine but not allowed:

CodeStatusMeaning
missing_api_key401No Authorization header, or not a bearer token.
invalid_api_key401The key is not a PressProve key, or is not known.
api_key_revoked401The key was revoked.
missing_scope403The key lacks the scope this endpoint needs.
account_frozen403The account is frozen. Reads work; writes do not.

JSON

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "param": null,
    "request_id": "req_0Lr8L2F9yU1hFe3vC8xDmL"
  }
}

Repeated wrong keys from one place are slowed down: see Limits. Every error carries a request_id; quote it if you write to us.