> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pruva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How Pruva authenticates API requests with your key.

Every request to the Pruva API, except the [health check](/api-reference/health), is authenticated with an API key sent in the `X-Pruva-Key` header.

```bash theme={null}
curl https://api.pruva.africa/v1/nin \
  -X POST \
  -H "X-Pruva-Key: pruva_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nin": "12345678901" }'
```

## Key format

A key has three parts, joined by underscores:

```text theme={null}
pruva_test_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
      ────  ────────────────────────────────────────
      env   secret
```

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.

<Warning>
  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.
</Warning>

## 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:

| Response                            | Reason                                                                                      |
| ----------------------------------- | ------------------------------------------------------------------------------------------- |
| `401 Missing API key`               | No `X-Pruva-Key` header was sent.                                                           |
| `401 Invalid API key`               | The key does not match any active key.                                                      |
| `401 This API key has been revoked` | The key was revoked in the dashboard.                                                       |
| `403 not yet approved`              | Your organization is not yet approved to run live checks.                                   |
| `403 suspended`                     | Your organization is suspended. Contact support.                                            |
| `403` on a scope                    | The key is not allowed to run that scope, or the scope is not active for your organization. |

<Note>
  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](/get-started/environments).
</Note>

## Keeping keys safe

<CardGroup cols={2}>
  <Card title="Never ship keys to the browser" icon="eye-slash">
    API keys belong on your server. For anything running in a browser, use the [Widget](/widgets/overview), which uses a public widget key with a different, limited scope.
  </Card>

  <Card title="Use a secret manager" icon="vault">
    Keep keys out of source control and config files. Load them from environment variables or a secret store at runtime.
  </Card>

  <Card title="One key per surface" icon="layer-group">
    Separate keys for production, staging, and each service make revocation surgical instead of disruptive.
  </Card>

  <Card title="Revoke on any doubt" icon="rotate">
    Revoking and rotating a key costs nothing. A leaked key left live can cost a great deal.
  </Card>
</CardGroup>