Skip to content

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

Package access

User GET /v1/packages Create a request Read package schema, requests, or reports using headers
Owner Every package exposed to the API Yes Any request in the organisation
Member with reference and/or background-check permission The packages that permission covers Yes Requests on those packages. A Contributor only sees requests they created.
Member with neither reference nor background-check permission 200 with "packages": [] No No
Support Every package exposed to the API No Any request in the organisation

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

A request to GET /v1/packages includes both authentication headers:

X-Xref-API-Key: <api-key>
X-Xref-User-Email: <user@yourcompany.com>

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, Support, 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.