Authentication

Every API request requires a Client ID and Client Secret sent as headers.

API Key Format #

Client ID:     audit1_{env}_cli_{32chars}
Client Secret: audit1_{env}_sec_{32chars}

Required Headers #

X-Client-ID: audit1_test_cli_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
X-Client-Secret: audit1_test_sec_f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3
Content-Type: application/json

Creating API Keys #

1. Log into your portal:
2. Employers: employer.audit1.com
3. Payroll Companies: provider.audit1.com
4. Go to Settings > Connections > Set Up Connection > API Keys
5. Choose New API v2.0 > Generate API Credentials
6. Copy both values — the Client Secret is shown only once

Key Scope #

Every API key is created with a scope that restricts which APIs it can call:

Calls to an endpoint outside your key's scope are refused — 403 insufficient_scope on the payment APIs, 401 Unauthorized elsewhere. Issue separate keys per workload — never reuse a payments-scoped key on payroll endpoints and vice versa.

An unrecognised scope is rejected at creation (400 scope_invalid) rather than stored — a typo like payment would otherwise produce a key that silently could not pay.

IP Allowlist #

An API key can be pinned to the addresses it may be used from. A copied key is then useless everywhere else, which is the single most effective thing you can do about a credential that has leaked.

By default there is no allowlist and nothing changes — a key without one works from anywhere, exactly as before. Ask Audit1 to pin a key once you know your egress addresses.

A pinned key presented from any other address gets a distinct error:

{
  "error": "IP_NOT_ALLOWED",
  "message": "This API key is restricted to an address allowlist and 203.0.113.7 is not on it. Nothing was read or written."
}

Service Account Binding (Google Cloud callers) #

The same protection as the IP allowlist, for callers that have no usable address: your service account proves who it is with a Google-signed identity token.

By default there is no binding and nothing changes — a key without one works with no token, exactly as before. The token is a second factor, never a replacement: X-Client-ID and X-Client-Secret are still required and are still checked first.

Mint the token from the metadata server — no keys, nothing to rotate:

curl -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://apiv2.audit1.com"

Send it in its own header, next to the usual credentials (Authorization stays free):

X-Client-ID: audit1_live_cli_…
X-Client-Secret: audit1_live_sec_…
X-GCP-ID-Token: eyJhbGciOiJSUzI1NiIs…

The audience is per-host. A token minted for https://apiv2.audit1.com is refused at https://payments.audit1.com, and vice versa — that is the replay boundary doing its job. Call both services? Mint two tokens.

The two controls compose as an OR, not an AND. A key with both an IP allowlist and a service-account binding passes on either: a matching address, or a valid token from a listed account. That is what lets one credential serve a pinned office and a cloud service. Only Google service accounts (*.gserviceaccount.com) can be bound.

Environments #

Both sandbox and production use the same URL. Your key prefix determines the environment automatically.

https://apiv2.audit1.com/api/v2

// Environment is determined by your key prefix — no code changes
const clientId = process.env.AUDIT1_CLIENT_ID;     // test or live
const clientSecret = process.env.AUDIT1_CLIENT_SECRET;

Signed Requests (Optional HMAC) #

For extra security, sign requests with HMAC-SHA256. This prevents replay attacks and request tampering.

Additional Headers #

X-Signature: a1b2c3d4e5f6...
X-Timestamp: 1704538800000

How to Compute #

payload = "${timestamp}.${method}.${path}.${body}"
signature = HMAC-SHA256(client_secret, payload)

• timestamp: Unix milliseconds (must be within 5 minutes of server time)
• method: HTTP method (POST, GET)
• path: Request path (/api/v2/payroll/reports)
• body: Raw request body (empty string for GET)

JavaScript #

const crypto = require("crypto");

function signRequest(clientSecret, method, path, body) {
  const timestamp = Date.now().toString();
  const payload = `${timestamp}.${method}.${path}.${body}`;
  const signature = crypto
    .createHmac("sha256", clientSecret)
    .update(payload)
    .digest("hex");
  return { "X-Signature": signature, "X-Timestamp": timestamp };
}

Python #

import hmac, hashlib, time

def sign_request(client_secret, method, path, body):
    timestamp = str(int(time.time() * 1000))
    payload = f"{timestamp}.{method}.{path}.{body}"
    signature = hmac.new(
        client_secret.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()
    return {"X-Signature": signature, "X-Timestamp": timestamp}

️ Key Management Best Practices #

Audit Logging #

Every API request is logged with: request ID, client ID, timestamp, HTTP method/path, response status, response time, signature validation result, and the client address enforcement resolved.

View logs in your portal under Developer > API Usage.