WHIZZHIRE
Docs · Authentication

One header, every call.

All /v1 endpoints authenticate with a bearer API key. No OAuth dance, no session cookies — a single Authorization header.

Authenticated request
curl https://hire.whizztech.ai/v1/jobs \
  -H "Authorization: Bearer wz_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Key format#

Keys follow the Stripe convention: a mode prefix followed by 43 characters of base64url-encoded randomness — 256 bits of entropy.

FieldTypeDescription
wz_live_…live keyFor production traffic. Create and revoke at Dashboard → API Keys.
wz_test_…test keyFor development and CI. Test keys hit the same API with the same behavior — the separate prefix exists so you can rotate or revoke development credentials without touching production, and tell environments apart at a glance.

How keys are stored#

  • Shown once. The full key appears exactly once, at creation. It cannot be retrieved again — the dashboard displays only the first 12 and last 4 characters.
  • Hashed at rest. Only a SHA-256 hash of the key is stored. Verification hashes the presented key and compares in constant time, so a database leak does not leak usable credentials.
  • Revocable instantly. Revoked keys fail with 401 on the next request. Each key records last_used_at so you can spot dead keys before rotating.

Failure shapes#

A missing header, malformed key, unknown key, or revoked key all return the same 401 — the API deliberately does not reveal which:

401 Unauthorized
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "invalid_api_key",
    "message": "Missing or invalid API key. Pass it as: Authorization: Bearer wz_live_..."
  }
}

Two neighboring failures worth knowing: 402 insufficient_credits when the org balance cannot cover an operation, and 429 rate_limit_exceeded when a key exceeds its per-minute budget (default 60 requests/min). Both use the same error envelope — see Errors and Rate limits.

Handling keys safely#

  • Call the API from your server only. A key in browser or mobile code is public within hours.
  • Inject keys via environment variables or a secret manager — never commit them. If a key lands in git history, revoke it; scrubbing history is not enough.
  • Use one key per service or environment so revocation has a small blast radius, and rotate by creating the new key before revoking the old one — both stay valid during the switchover.
NextJobs→