Skip to main content

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

1

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.
2

Receive and store it

VitaRelay sends you the raw key. Put it straight into your secret store or environment variables.
3

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.
4

To rotate or revoke, contact VitaRelay

Key lifecycle changes are always a request to VitaRelay — there is no dashboard action on your side.

​
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. 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.
If you need a scope your current key does not have, ask VitaRelay to issue a replacement key with the additional scope.

​
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 and 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.
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.

​
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:
1

Ask for a replacement

Request a second key with the same environment and scopes. Both keys work during the overlap.
2

Deploy the new key

Update your secret store and roll out, then confirm traffic is using the new key.
3

Ask VitaRelay to revoke the old key

Once nothing is using it, request revocation of the previous key.
Rotate proactively at least once a year, and contact VitaRelay immediately after any suspected exposure so the key can be revoked.

​
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.