Authentication

Authentication allows Davix H2I to verify that a request is authorized to use the platform.

Every request sent to the public API must include a valid API key. Requests without valid authentication are rejected before processing. External API routes use API key authentication for access control across the /v1/* endpoints.

Why Authentication Is Required #

Davix H2I provides backend processing operations such as HTML rendering, image processing, PDF processing, and tool-based media operations. Because these requests consume platform resources, access is restricted to authorized clients.

Authentication allows the platform to:

• verify the client making the request
• control access to public API capabilities
• enforce quotas and rate limits
• reject unauthorized requests before processing begins

Only authenticated public API requests continue through the request pipeline and reach the H2I engine (PixLab) for processing.

API Key Authentication #

Davix H2I uses API keys to authenticate requests to the public API.

Each client must include its API key in the request headers on every call to /v1/*. The authentication middleware accepts two header formats for external requests.

Supported Authentication Methods #

You can authenticate requests using either of the following headers:

Option 1 — Authorization Header #

Send your API key as a bearer token:

Authorization: Bearer <YOUR_API_KEY>

Option 2 — X-Api-Key Header #

Send your API key directly in a dedicated header:

X-Api-Key: <YOUR_API_KEY>

Both header methods are accepted for public API requests.

Authentication Rules #

To ensure consistent and secure authentication behavior:

• API keys must be sent in request headers
• Authorization: Bearer <key> is supported
• X-Api-Key: <key> is supported
• in production, API keys sent in the request body or query string are rejected
• query parameters such as ?key= are not supported for production use
• request body fields such as api_key are not supported for production use

In production environments, if an API key is supplied through the query string or request body, the API returns api_key_location_not_allowed with HTTP 400.

Authentication Workflow #

Each authenticated public API request follows this general sequence:

1. Request Received #

The API receives the HTTP request.

2. Credential Extraction #

The authentication layer reads the API key from either:

• Authorization: Bearer <key>
• X-Api-Key: <key>

3. Credential Validation #

The API validates the supplied key.

4. Access Decision #

If the key is valid, the request continues through the endpoint pipeline. If the key is missing, invalid, or expired, the request is rejected.

5. Request Processing #

After authentication succeeds, the request proceeds to the relevant endpoint and can be forwarded for processing by the H2I engine (PixLab).

Example Authenticated Request #

Using X-Api-Key #

curl -sS -X POST "https://pixlab.davix.dev/v1/h2i" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: h2i-auth-example-001" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "image",
    "html": "<div style=\"width:100%;height:100%;display:flex;align-items:center;justify-content:center\">Hello</div>",
    "css": "body{margin:0}",
    "width": 1200,
    "height": 1600,
    "format": "jpeg"
  }'

Using Authorization: Bearer #

curl -sS -X POST "https://pixlab.davix.dev/v1/h2i" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Idempotency-Key: h2i-auth-example-002" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "pdf",
    "html": "<h1>Invoice</h1>",
    "css": "body{font-family:sans-serif}",
    "width": 1000,
    "height": 1500,
    "pdfFormat": "LETTER",
    "pdfLandscape": false,
    "pdfMargin": 24,
    "preferCSSPageSize": true,
    "scale": 1,
    "printMode": false,
    "printBackground": true
  }'

These examples are aligned with the documented external authentication behavior and the verified /v1/h2i request structure.

Optional: Idempotency Key #

Davix H2I supports optional idempotency headers for request correlation and retry safety.

You can send either of these headers:

• Idempotency-Key
• X-Idempotency-Key

Valid idempotency keys must:

• be non-empty
• be between 8 and 128 characters
• use only the allowed character set: A-Z, a-z, 0-9, ., _, :, -

When a valid idempotency key is provided, the API echoes it back in the Idempotency-Key response header. If the value is invalid, the API returns invalid_idempotency_key with HTTP 400.

Authentication Errors #

If authentication fails, the API returns a structured error response.

Common authentication-related errors include:

• invalid_api_key — the API key is missing or invalid
• key_expired — the customer API key has expired
• api_key_location_not_allowed — the API key was supplied in the query string or request body in production

These errors are returned before request processing begins.

Keeping Your API Key Secure #

Your API key grants access to the platform and should be treated as a secret.

Recommended practices:

• store the key in environment variables or secure secret storage
• never expose the key in client-side browser code
• never commit the key to repositories
• limit access to the systems and team members that require it
• rotate or replace the key if it is ever exposed

These practices are consistent with the platform’s header-based authentication model for server-side use.

Authentication in Integrations #

Authentication is required regardless of how Davix H2I is used. This includes:

• direct API integrations
• backend services
• automation workflows
• integration-based usage such as website or workflow tooling

In integration environments, the API key is typically configured once and then automatically attached to outgoing requests. This matches the platform’s API-first integration model.

Summary #

Davix H2I uses API key authentication to protect access to its public API.

Every public API request must include a valid API key in request headers. The supported authentication methods are Authorization: Bearer <key> and X-Api-Key: <key>. In production, API keys supplied in the request body or query string are rejected. Optional idempotency headers are also supported for safer retries and request correlation. Once authentication succeeds, the request can continue to the H2I engine (PixLab) for processing.