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

# Authentication

> How ProVision Public API keys are created, sent, and rotated.

Every Public API request must include the API key as the value of the `x-api-key` HTTP
header. Keys are tenant-scoped: a key issued to Partner A cannot read Partner B's data.

## Sending the key

```http theme={null}
GET /v1/health HTTP/1.1
Host: connect.provisionapp.io
x-api-key: … (your key here)
```

Sending the key via `Authorization: Bearer …` is **not** supported. Sending no key returns
`403 Forbidden`. Sending a key the gateway does not recognise also returns `403 Forbidden`.

## Getting a key

Authorized admin users create keys in the ProVision portal under **Settings → Integrations → Developer**.

1. Open the **Developer** tab.
2. Click **Create key**.
3. Enter a name and select the [operation scopes](/permissions) the integration needs.
4. Copy the full key from the one-time reveal dialog and store it in your secret manager.

Keys are **partner-scoped**, not per user. Any integration using the key acts on behalf of
your partner tenant. Choose the minimum scopes needed for your use case.

The full key value is shown only at creation (and again after regeneration). If you lose it,
use **Regenerate key** on the Developer tab to issue a new secret.

If you do not see the Developer tab, ask a ProVision admin on your team to grant access or
create a key for you. For help choosing scopes, email
[help@onevisionresources.com](mailto:help@onevisionresources.com).

## Rotation and revocation

To rotate a key, open **Settings → Integrations → Developer**, choose the key, and select
**Regenerate key**. Deploy the new secret to your integration before deleting the old value
from your secret manager.

To revoke a key immediately, choose **Revoke key** from the row menu. Revoked keys stay
visible in the list with a `REVOKED` label but can no longer authenticate requests.

If a key is leaked and you cannot sign in to the portal, email
[help@onevisionresources.com](mailto:help@onevisionresources.com) with the prefix of
the key (the first eight characters) and the words "REVOKE NOW" in the subject line.

## What the key proves

A valid key proves three things to the API:

1. **Tenancy.** The key is bound to a `partnerId` in our internal database, and that is the
   only tenant the request can read or write.
2. **Allowed operations.** The key carries a list of operation scopes (for example
   `conversation:read`) that gate each endpoint — see [Permissions](/permissions).
3. **Throttle bucket.** The key counts against a per-key rate limit enforced at the API
   gateway — see [Rate limits](/rate-limits).