Getting Started with the Klau API

1. Authentication

All API requests authenticate with an API key in the Authorization header. Keys are created in Settings → Developer, or by a platform operator for vendor accounts.

Key Types

• Direct Keys: Tied to a specific company or division. All requests are automatically scoped to that tenant's data. No extra headers required.
• Vendor Keys: Tied to a platform integrator account with no company. Can access multiple haulers, but every request must include the Klau-Tenant-Id header to specify which hauler you're acting on behalf of.

2. Enterprise: Division-Scoped Keys

If your organization operates multiple divisions (markets or regions), each division is a fully isolated tenant with its own data, settings, and API keys. To integrate with a specific division, create an API key inside that division.

Each key only has access to its own division's jobs, drivers, customers, and settings. There is no cross-division access. If you need to integrate with multiple divisions, create a key in each one.

3. Multi-Tenancy (Vendor Keys)

If you are a platform integrator managing multiple haulers, pass the target company's ID in the Klau-Tenant-Id header. The vendor must have an active partnership with that company, and the tenant must have granted the required access scopes.

GET /api/v1/jobs?date=2026-03-15
Authorization: Bearer kl_live_vendor_key_here
Klau-Tenant-Id: <company-uuid>

If the header is missing or the vendor has no access to that tenant, the API returns 403 Forbidden.

4. Scopes

API keys and vendor tenant grants are scoped to specific resources. The API derives the required scope from the HTTP method and URL path:

• GET / HEAD → read:<resource>
• POST / PUT / PATCH / DELETE → write:<resource>

Available resources:

Wildcards are supported: read:all, write:all, read:*, write:*.

5. Response Format

All responses follow a consistent JSON structure. Successful responses wrap data in a data field. Errors use an error field with code and message.

// Success
{ "data": { ... } }

// Error
{ "error": { "code": "NOT_FOUND", "message": "Job not found" } }

6. Rate Limiting

The API enforces rate limits per authenticated identity (developer account or IP).

Exceeding the limit returns 429 Too Many Requests.

7. Idempotency

For safe retries on network failures, include an Idempotency-Key header on any non-GET request. If the same key is sent again within 24 hours, the API returns the cached response from the original request.

POST /api/v1/jobs
Authorization: Bearer kl_live_xxx
Idempotency-Key: unique-request-id-123
Content-Type: application/json

{ ... }

A cache hit includes the header X-Idempotency-Hit: true.