Authentication & API Keys

All inference requests (both Elastic and Dedicated) require authentication via a Bearer token.

API Key Format

Keys always start with the hvz_live_ prefix and are 42 characters long:

hvz_live_3f8a9c2e1b4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c

Keys are generated server-side using cryptographically secure random values and stored hashed (only the prefix is shown in the UI after creation).

Creating Keys

1. In the dashboard, go to Settings → Keys.
2. Click Create New Key.
3. Provide a human-readable name and select a scope.

Currently supported scopes:

• inference — Can call both Elastic and your own Dedicated endpoints.
• global — (Legacy) Broad access. Prefer inference for new keys.

Every new user automatically receives one default inference key upon signup (via database trigger).

Using Keys

Elastic Inference

POST /api/chat/completions
Authorization: Bearer hvz_live_...
Content-Type: application/json

Dedicated Inference

POST /api/d/{endpoint-id}/chat/completions
Authorization: Bearer hvz_live_...

Public Dedicated Endpoints

When you create a Dedicated endpoint and set Auth Mode = Public, the endpoint can be called without any Authorization header. This is useful for:

• Sharing demos
• Building public-facing products on top of your endpoint
• Internal tools where you handle auth at a higher layer

Security note: Public endpoints are still rate-limited at the platform level and tied to your account for billing/quotas.

Session vs API Key Authentication

The inference APIs support two modes:

If you call the API from a browser while logged into the dashboard without a Bearer token, the system will look for a session and require that you have at least one active inference key. This is intentional friction to prevent accidental keyless usage.

Key Management Best Practices (MVP)

• Create separate keys for different environments (prod, staging, ci).
• Rotate keys periodically (the dashboard allows instant revocation).
• Never embed keys in client-side code that is shipped to untrusted users.
• For public endpoints, consider putting your own lightweight auth (JWT, etc.) in front of the Hypervize URL.

Revoking Keys

1. Go to Settings → Keys.
2. Click the trash icon next to any key.
3. The key is immediately deactivated. In-flight requests using the old key will fail with 401 Invalid API key.

There is no grace period.

Future Enhancements (Post-MVP)

• Per-key rate limits
• Usage analytics per key
• Key expiration dates
• Fine-grained scopes (e.g., elastic-only, dedicated:read)

These are tracked in the internal roadmap.

Related Reading

• Quickstart — First Inference Call
• Elastic Inference API
• Dedicated Inference Endpoints