Copy page

Core API

Environments and Testing

HollyHR public API keys are organisation-scoped. The token prefix tells you which environment owns the key:

• hhr_live_: a live organisation key.
• hhr_test_: a key created inside HollyHR's platform-owned synthetic sandbox organisation at sandbox.hollyhr.com.

GET /me reports the resolved environment for the presented key:

Code
{
  "environment": {
    "type": "live",
    "sandbox": false
  },
  "actor": {
    "type": "api_key"
  }
}

For a sandbox key, the same field is:

Code
{
  "environment": {
    "type": "sandbox",
    "sandbox": true
  },
  "actor": {
    "type": "api_key"
  }
}

There is no hidden sandbox behind hhr_live_ keys. A live organisation key always acts on the live organisation that created it, even when used from the developer-docs playground. Treat every successful write with a live key as a live organisation change.

How to test safely

Use a non-production HollyHR organisation for integration development whenever possible. Create a dedicated API key for that organisation, grant only the scopes required by the test, and keep the key separate from production configuration.

When testing against a live customer organisation:

• start with read-only scopes;
• use small, clearly named test records;
• use idempotency keys on every write;
• read the resource first and send If-Match when the endpoint requires an ETag;
• verify webhook receivers with POST /webhooks/{webhookId}/test before subscribing to production events;
• use GET /me in startup checks so the integration logs the organisation, key id, granted scopes, actor type, and live environment before doing work.

Base URLs

Use the same app origin the organisation uses to sign in:

Code
export HOLLYHR_API_BASE_URL="https://{workspace}.hollyhr.com/api/v1"

If the organisation uses a custom HollyHR domain, use that custom origin instead. Local, preview, and staging app deployments are not a public sandbox contract and should not be used as customer integration targets unless HollyHR has explicitly arranged that with you.

For the hosted synthetic sandbox, use:

Code
export HOLLYHR_API_BASE_URL="https://sandbox.hollyhr.com/api/v1"
export HOLLYHR_API_TOKEN="hhr_test_..."

Sandbox keys are still tenant-scoped credentials. They do not grant access to a customer's live organisation, and they should not be copied into production integration configuration.

Future self-service sandbox orgs

The current public test-key contract is the platform-owned synthetic sandbox tenant. Per-customer self-service sandbox organisation provisioning remains a future feature. It will not be introduced by silently changing live-key behaviour.