---
title: API keys, scopes, rotation and sandbox | HelpRange developers
url: https://www.helprange.com/developers/keys
---

Developers

# API keys, scopes, rotation and the sandbox

How to authenticate to the HelpRange REST API with least-privilege keys, rotate them without downtime and test safely in test mode.

## API keys

Every request to the HelpRange REST API (`/api/v2/…` and the older `/public-api/…`) carries an API key. Administrators create keys in **Settings → API keys**. Give every integration its own key, with only the scopes it needs, so you can roll or revoke one without touching the others.

- **Format:** `hr_live_` or `hr_test_` followed by 40 letters and digits.
- **Shown once.** HelpRange stores only a SHA-256 hash of the key and its first characters (e.g. `hr_live_Ab3x9K…`) to recognise it in the list. Copy the key when you create it; if you lose it, roll it.
- **Who it acts as:** the administrator who created (or last rolled) the key, with their permissions. If that person leaves the team the key stops working (`401 key_owner_removed`) until another administrator rolls it.
- **Plans:** the same as before – the REST API is available on the Max and Unlimited plans, the Deal Room Pass and the trial (`402` otherwise), for live and test keys alike.

### Sending the key

```
curl https://www.helprange.com/api/v2/documents \
  -H "Authorization: Bearer hr_live_…"
```

`X-API-Key: hr_live_…` and `Authorization: Api-Key hr_live_…` work too; the v1 API also takes the bare key in `Authorization`.

### Errors

| `401 invalid_key` | Unknown key. |
|---|---|
| `401 key_revoked` | The key was revoked (or its roll overlap ended). |
| `401 key_expired` | The key's expiry date has passed. |
| `401 key_owner_removed` | The key's creator is no longer in the team – roll it. |
| `403 insufficient_scope` | The key lacks the endpoint's scope; `required_scope` names it. |
| `400 sandbox_email_domain` | Test mode only accepts e-mail addresses at reserved test domains. |

```
{"error": "This API key does not have the \"rooms:write\" scope needed for POST /api/v2/data-rooms/12/guests. …",
 "code": "insufficient_scope", "required_scope": "rooms:write", "key_scopes": ["documents:read", "rooms:read"]}
```

## Scopes

A key can call an endpoint only when it has the endpoint's scope – least privilege. Reading needs `…:read`; creating, changing and deleting need `…:write`. Presets: **Read-only** (every `:read` scope) and **Full access** (all scopes).

| `documents:read` | List folders, documents, subfolders, e-signature requests and files uploaded by clients. |
|---|---|
| `documents:write` | Upload documents, create and change folders and subfolders, send and manage e-signature requests. |
| `links:read` | Read share links of documents, offers and lead-form templates. |
| `links:write` | Create share links, give or remove buyer access, create and change offers. |
| `rooms:read` | Read data rooms: details, index, guests' access requests, Q&A, request lists, folders, documents. |
| `rooms:write` | Change data rooms: invite guests, answer Q&A, request lists, room folders and documents. |
| `analytics:read` | Read views, statistics, activity, offer responses and store sales. |
| `webhooks:manage` | Reserved for managing webhook endpoints through the API (no endpoint uses it yet – webhooks are set up in Settings → Integrations). |
| `team:read` | Read the team: who the key belongs to, the plan and its limits. |

Main endpoints per scope: `documents:*` – folders, documents, uploads, subfolders, e-signature requests; `links:*` – share links, buyer access, offers, lead-form templates; `rooms:*` – data rooms, guests, Q&A, request lists, room folders and documents; `analytics:read` – views, statistics, activity, offer responses, store sales; `team:read` – `/api/v2/me` and `/api/v2/plan`; `webhooks:manage` – reserved (webhooks are set up in Settings → Integrations; no API endpoint needs it yet).

## Rotation and revocation

- **Roll key** creates a new secret with the same name, scopes, mode and expiry. Choose how long the old key keeps working: **not at all**, **24 hours** or **7 days** – long enough to deploy the new key everywhere. After the overlap the old key is revoked automatically.
- **Revoke** stops a key immediately (also an old key that is still in its overlap).
- **Expiry date** (optional): the key stops working at the end of that day (UTC).
- Every create, roll and revoke is recorded in **Activity → Team** with who did it. The list shows when each key was last used.
- **Legacy keys**: the single per-member key from before (shown as “Legacy key (full access, live)”) keeps working with full access. Migrate by creating a scoped key and switching your integration to it.

## Sandbox (test mode)

Keys starting with `hr_test_` work on a separate **sandbox** of your team – never on your live data, and live keys never see the sandbox. The first test request creates it with sample data: two documents with share links and sample views, and a data room with two guests at example.com / example.org.

- Every response says `"livemode": false` (and the header `X-HelpRange-Livemode: false`); live keys answer `"livemode": true`.
- **No e-mails are sent.** Invitations, signature requests and notifications are logged instead – see “E-mails the sandbox did not send” in Settings → API keys. To make sure nobody real is ever e-mailed, test mode accepts only addresses at reserved test domains such as `jane@example.com`, `guest@example.org` or `anyone@acme.test`.
- **No payments:** nothing in the sandbox talks to Stripe.
- **Webhooks:** sandbox activity does not trigger your webhook. To test your receiver, use **Send test event** in Settings → Integrations → Delivery log (the event carries `"test": true`).
- The sandbox does not count towards your plan's limits, statistics or billing. API rate limits and daily caps are counted separately for it.
- **Reset sandbox** (Settings → API keys) deletes all sandbox data; the next test request starts a fresh one. Sandbox data is deleted automatically 30 days after the sandbox was created or reset.

```
curl https://www.helprange.com/api/v2/documents -H "Authorization: Bearer hr_test_…"
{"documents": [{"id": 9182, "name": "Sample – Investor Deck.pdf", …}], "livemode": false}
```