Authentication

All endpoints under /v1/* require authentication via an API key. Health check endpoints (/health/live and /health/ready) are public and do not require authentication.

API Key Format

API keys follow a structured prefix format that indicates the environment:

Prefix pattern	Environment
zf_live_sk_...	Production
zf_test_sk_...	Test

The first 12 characters of the key serve as a prefix used for fast project lookup via cache. The full key is verified against a stored SHA-256 hash to prevent timing attacks.

Using the API Key

Include your API key in the Authorization header as a Bearer token on every /v1/* request:

Authorization: Bearer <your_api_key>

curl example

curl -X GET https://api.zeridion.com/v1/jobs \
  -H "Authorization: Bearer zf_test_sk_local_development_key"

C# HttpClient example

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "zf_test_sk_local_development_key");

var response = await client.GetAsync("https://api.zeridion.com/v1/jobs");

tip

If you are using the Zeridion.Flare SDK, authentication is handled automatically. Set your API key in configuration:

builder.Services.AddZeridionFlare(options =>
{
    options.ApiKey = "zf_test_sk_local_development_key";
});

Request ID

Every authenticated request is assigned a unique request ID (a ULID) by the authentication middleware. This ID:

• Is generated before any endpoint logic runs
• Is included in all error responses as request_id
• Can be used when contacting support to trace a specific request

Auth Flow (Internal)

1. ApiKeyAuthMiddleware checks if the path starts with /v1
2. Extracts the Bearer token from the Authorization header
3. Calls ITenantResolver.ResolveAsync(prefix, fullKey) which checks IDistributedCache first
4. On cache miss, queries the database by API key prefix
5. Verifies the SHA-256 hash of the full key matches the stored hash
6. Caches the resolved project for 5 minutes

Error Responses

If authentication fails, the API returns a 401 Unauthorized response:

Status	Code	When
401	unauthorized	Missing Authorization header, invalid Bearer format, unknown key, hash mismatch

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key.",
    "request_id": "01JAXBKM3N4P5Q6R7S8T9UVWXY"
  }
}

See the Errors page for the full error code reference and the Rate Limits page for request throttling details.