Header
Authorization: Bearer $PRESSPROVE_API_KEYA 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
| Key | What 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.
| Scope | Allows | Endpoints |
|---|---|---|
read | Read anything of the account: checks, monitors, reports, releases, balance, usage, ledger, events. | 16 |
checks:write | Create and cancel checks. | 2 |
monitors:write | Create, pause, resume, end and run monitors. | 5 |
reports:write | Create proof reports. | 2 |
releases:write | Order and approve paid press releases. Off by default; you switch it on for a key. | 3 |
Replace a key
- Make a new key with the same scopes.
- Put it in your software and deploy.
- Check under Keys that the old key was last used before the deploy.
- 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:
| Code | Status | Meaning |
|---|---|---|
missing_api_key | 401 | No Authorization header, or not a bearer token. |
invalid_api_key | 401 | The key is not a PressProve key, or is not known. |
api_key_revoked | 401 | The key was revoked. |
missing_scope | 403 | The key lacks the scope this endpoint needs. |
account_frozen | 403 | The 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.