Authentication

The Xref API authenticates requests using two HTTP headers:

Header	Required	Description
X-Xref-API-Key	Yes	API key generated in Organisation Settings → Xref API. Identifies the organisation making the request.
X-Xref-User-Email	Yes	Email address of the Xref user associated with the request. Must match an active user associated with the organisation that owns the API key.

Both headers are required on every request to a /v1/* endpoint, with two specific exceptions:

1. GET /v1/ping — health check endpoint that does not require authentication.
2. GET /v1/reports/* — report download endpoints accessed using a valid signed ?t= query token.

If either header is missing outside these exceptions, the API returns 401 client_error. An invalid or revoked API key also returns 401.

Signed report tokens (?t=...)

Report download URLs returned by GET /v1/requests/{id} include a signed query parameter (t) that allows the report to be downloaded without authentication headers.

• Background check reports: /v1/reports/{check_id}?t=<signed_token>
• Reference check reports: /v1/reports/{check_id}/referees/{referee_id}?t=<signed_token>

An expired or invalid token returns 401 client_error. Retrieve the request again using GET /v1/requests/{id} to obtain a new report URL.

How the authentication headers are used

The API key identifies the organisation associated with the request. Each API key belongs to a single organisation and determines which packages, requests, and webhooks are accessible.

The user email identifies the Xref user the request is made on behalf of. Xref attributes the resulting request to this user in audit logs and in the Xref platform. The user's role within the organisation also determines which packages are available and the actions they can perform.

If the user email does not match an active Xref user in the organisation associated with the API key, the API returns 403 client_error.

Worked example

curl -X GET https://api.xref.com/v1/packages \
  -H "X-Xref-API-Key: 4e7d5c8a9b6f4d3e8a2c1d5f6e9b3a7c" \
  -H "X-Xref-User-Email: jane.doe@yourcompany.com" \
  -H "Accept: application/json"

A successful response uses the standard envelope:

{
  "data": { "packages": [/* ... */] },
  "status_message": "ok",
  "message": ""
}

Obtaining and rotating an API key

1. Sign in to Xref as an organisation Owner.
2. Navigate to Organisation Settings → Xref API.
3. Select Generate API key. The API key is displayed only once and should be stored securely.
4. To rotate the API key, generate a new key and update the stored credentials. The previous key is revoked when the new key is generated.

API keys are 32-character opaque values generated using cryptographically secure randomness and should be treated as secrets. Possession of a valid API key grants access on behalf of the associated organisation.

Role-based visibility

Each Xref user has an assigned role (Owner, Admin, Member). The user's role determines which packages are available and which actions can be performed. See GET /v1/packages for details.

If the user's role does not permit an action, the API returns 403 client_error.

Throttling

The API enforces two fixed-window quotas per API key:

Window	Default limit
60 seconds	60 requests
1 hour	1 000 requests

Breaching either window returns 429 client_error with a Retry-After header containing the number of seconds until the window resets.

/v1/ping is exempt from throttling.

Security notes

• All API requests must use HTTPS. Plain HTTP requests are rejected.
• API keys must not be included in URLs, query strings, browser code, or client-side applications. API keys should be stored and used server-side only.
• Rotate API keys when access is no longer required by a team member.