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-app-prod.netchexonline.net/accounts/me?api-version=3.0" \
  -H "X-API-KEY: abc123xyz..."

Getting an API Key

API 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 integration has access to.

• Passing a company-id you don't have access to will return an empty result (not a 403)
• Passing an organization-id containing no accessible companies returns an empty result
• Passing an employee-id belonging to an inaccessible company returns 404

This is by design — it prevents leaking the existence of data your integration should not see.

Security Best Practices

• 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 — contact the Netchex Integrations team immediately
• 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-app-prod.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.