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

# API Keys

> How VitaRelay issues your API key, what it can do, and how to rotate or revoke it.

# API Keys

Your API key is **issued by VitaRelay**. A VitaRelay super admin creates the key
for your organization and shares the raw value with you directly. There is no
self-serve key management: you cannot mint, rotate, or revoke keys yourself.

To obtain a key — or to rotate or revoke one — contact your VitaRelay
representative.

## What a key looks like

A key is an opaque string with an environment prefix:

```bash theme={null}
vr_live_xxxxxxxxxxxxxxxxxxxx
vr_test_xxxxxxxxxxxxxxxxxxxx
```

Each key belongs to exactly one environment and one organization, and it acts
only on that organization's records. Treat it like a password: store it in a
secret manager, never commit it to source control, and use one key per
integration so a single key can be replaced without affecting anything else.

## How to get a key

<Steps>
  <Step title="Request a key">
    Ask your VitaRelay representative for a key. Tell them which environment you
    need (**test** to build against the sandbox, **live** for production) and
    what your integration does, so the right scopes are granted.
  </Step>

  <Step title="Receive and store it">
    VitaRelay sends you the raw key. Put it straight into your secret store or
    environment variables.
  </Step>

  <Step title="Receive your webhook signing secret">
    If your integration receives webhooks, VitaRelay also configures your
    endpoint and shares the signing secret with you at the same time. See
    [Webhook Security](/webhooks/security).
  </Step>

  <Step title="To rotate or revoke, contact VitaRelay">
    Key lifecycle changes are always a request to VitaRelay — there is no
    dashboard action on your side.
  </Step>
</Steps>

## Scopes

Your key is granted the scopes your integration needs, chosen when VitaRelay
issues it. A request to an endpoint whose scope the key does not carry is
rejected with `403 insufficient_scope`.

| Scope                | Grants                                          |
| -------------------- | ----------------------------------------------- |
| `patients:read`      | `GET /patients`, `GET /patients/{id}`           |
| `orders:read`        | `GET /orders`, `GET /orders/{id}`               |
| `prescriptions:read` | `GET /prescriptions`, `GET /prescriptions/{id}` |
| `products:read`      | `GET /products`                                 |
| `patients:write`     | `POST /patients`                                |
| `intakes:write`      | `POST /intakes`                                 |
| `orders:write`       | `POST /orders`                                  |

Read scopes are available to any organization. Write scopes additionally require
that your organization is an active Vita Clinic — otherwise write requests are
rejected with `403 not_vita_clinic`, even when the scope is present.

<Note>
  If you need a scope your current key does not have, ask VitaRelay to issue a
  replacement key with the additional scope.
</Note>

## Environments

The prefix tells you which environment a key belongs to: `vr_live_` for
production and `vr_test_` for the sandbox. Both are sent to the **same base
URL** — see [Environments](/getting-started/environments) and
[Sandbox](/getting-started/sandbox).

## The key is shown once

The raw key is provided to you a single time. Store it immediately — VitaRelay
keeps only a hash of it and cannot look it up later.

<Warning>
  The raw key cannot be retrieved after it is shared. If you lose it, ask
  VitaRelay to revoke the old key and issue a new one.
</Warning>

## Rotating and revoking

Both are requests to VitaRelay. Revocation is immediate: the next request using
a revoked key returns `401 unauthorized`.

To rotate with zero downtime, coordinate the overlap with your VitaRelay
representative:

<Steps>
  <Step title="Ask for a replacement">
    Request a second key with the same environment and scopes. Both keys work
    during the overlap.
  </Step>

  <Step title="Deploy the new key">
    Update your secret store and roll out, then confirm traffic is using the new
    key.
  </Step>

  <Step title="Ask VitaRelay to revoke the old key">
    Once nothing is using it, request revocation of the previous key.
  </Step>
</Steps>

<Note>
  Rotate proactively at least once a year, and contact VitaRelay immediately
  after any suspected exposure so the key can be revoked.
</Note>

## Rate limits

Each key carries its own write rate limit, defaulting to 60 write requests per
minute. Reads are not rate limited. See
[Rate Limits](/getting-started/rate-limits).