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.info
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 return 401 Unauthorized. Issue separate keys per workload — never reuse a payments-scoped key on payroll endpoints and vice versa.

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, and signature validation result.

View logs in your portal under Developer > API Usage.