Skip to main content
Every request to the Pruva API, except the health check, is authenticated with an API key sent in the X-Pruva-Key header.

​
Key format

A key has three parts, joined by underscores:
The middle segment is the environment, test or live, so you can tell at a glance which key you are holding. The dashboard shows only the first twelve characters of a key after creation, as a label; the full secret is shown once and never again.
Pruva stores only a SHA-256 hash of your key, never the key itself. This means a lost key cannot be recovered. If a key is exposed, revoke it in the dashboard and create a new one.

​
Creating and managing keys

Create, name, and revoke keys in the dashboard under Developer, API keys. Each key is tied to one environment and to the set of scopes it is allowed to run.
  • Name your keys for where they run, for example production-backend or staging, so an exposed key is easy to trace and revoke.
  • Revoke a key the moment it is no longer needed or may have leaked. Revocation takes effect immediately; the next request with that key is rejected.
  • Rotate by creating the new key first, deploying it, then revoking the old one, so there is no gap in service.

​
What a key carries

When you authenticate, the key identifies your organization, its environment, and the scopes it may run. A request can fail authentication or authorization for a few distinct reasons:
Running a verification is a write action, so it requires an approved organization. You can still authenticate and explore in test before approval; see Environments.

​
Keeping keys safe

Never ship keys to the browser

API keys belong on your server. For anything running in a browser, use the Widget, which uses a public widget key with a different, limited scope.

Use a secret manager

Keep keys out of source control and config files. Load them from environment variables or a secret store at runtime.

One key per surface

Separate keys for production, staging, and each service make revocation surgical instead of disruptive.

Revoke on any doubt

Revoking and rotating a key costs nothing. A leaked key left live can cost a great deal.