Authentication

The Netchex External API supports two header formats for authentication. Use whichever fits your integration, both grant the same access.

Header Formats

Option 1: X-API-KEY (recommended)

X-API-KEY: YOUR_API_KEY

Option 2: Authorization with ApiKey prefix

Authorization: ApiKey YOUR_API_KEY

Do not use Bearer or any other scheme with the Authorization header.

Example using X-API-KEY:

curl -X GET "https://external-api.netchexonline.net/accounts/me?api-version=3.0" \
  -H "X-API-KEY: abc123xyz..."

Key Types

There are two kinds of API key, and both authenticate the same way, the header formats above work identically regardless of which one you use.

Client API key: self-service. Any user with the client-admin role on at least one company can create, rotate, and revoke their own keys from the API Keys portal, without contacting Netchex.

Integration key: Netchex-issued. Provisioned by the Netchex Integrations team when a third-party integration is set up; requires contacting your Netchex representative.

Both key types use the same authentication headers, and every v1, v2, and v3 endpoint accepts either key type, except the account endpoints (see below). Both are limited to the companies the key is scoped to, but effective permissions can vary by key type and endpoint. For example, Client API keys can only read pay rates for employees on whom the key's owner holds the View Pay Rate permission.

One exception: GET /accounts/me (v3) and GET /api/Account/Me (v1) return the Integration key's own account details and are only supported for Integration keys. For a Client API key, verify your key with GET /organizations instead, it works identically for both key types.

Getting an API Key

If you have the client-admin role on at least one company, you can create your own key:

Sign in and go to API Keys at integrations/portal/api-keys.
Select the companies the key should have access to.
Create the key and copy the generated value, it's only shown once.

You can rotate or revoke the key at any time from the same page.

This portal path may move once it's linked from the main navigation. If you can't find it, check with your Netchex representative for the current location.

Integration keys are provisioned by the Netchex Integrations team when your integration is set up. Contact your Netchex representative or email the integrations team to request access.

Scoped Access

Your API key is scoped to specific companies within the Netchex platform. When you make requests that return employee, payroll, or time data, the API automatically filters results to only the companies your key has access to.

Whether an inaccessible id comes back as an empty/partial result, a 404, or (on a small number of endpoints, such as the v1 pay-rates endpoint and the v3 shifts endpoints) a 403 is endpoint-specific, not determined by which filter type (company-id, organization-id, employee-id) you passed. Check the specific endpoint's own documentation (its remarks in the API Reference) for its exact behavior; see Error Handling for the full endpoint-by-endpoint breakdown.

How Client API key scope works

A Client API key's granted companies are fixed at creation time, they act as a ceiling, not a starting point. For example, say an admin has the client-admin role on companies 123, 234, 345, and 213, but only selects 123 and 234 when creating a key. That key can only ever reach {123, 234}, companies 345 and 213 were never granted to it, so they're not reachable even though the admin has access to them.

On every request, the key's granted companies are intersected against the admin's current client-admin access:

If the admin gains access to a new company later, the key's reach doesn't change, that company was never part of the key's grant.
If the admin loses access to a company the key was granted, the key immediately loses access to it too, on the very next request, no key edit required.

In short: a key's granted companies can only shrink from what the admin can currently reach, never expand beyond what was selected at creation.

Security Best Practices

Your API key grants access to real HR, payroll, and time data. Protect it accordingly.

Never commit your API key to source control
Use environment variables or a secrets manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
Rotate keys if you suspect a key has been compromised, do this yourself from the API Keys portal for a Client API key, or contact the Netchex Integrations team immediately for an Integration key
Do not log the Authorization header value in your application logs
Use HTTPS only, the API does not accept plain HTTP

Testing Authentication

To verify your key is valid:

curl -i "https://external-api.netchexonline.net/accounts/me?api-version=3.0" \
  -H "X-API-KEY: YOUR_API_KEY"

A 200 OK with your account details means authentication succeeded. A 401 Unauthorized means the key is invalid or not yet provisioned.