Gateway Integration

Alephant Gateway lets you route LLM requests through Alephant Virtual Keys instead of exposing raw provider keys in applications. Requests remain provider-compatible while Alephant applies authentication, routing, logging, budgets, policy checks, and analytics.

Configure a Virtual Key

1. Add a provider key in Keys. This is the upstream provider credential that Alephant stores securely.
2. Create an Agent or Virtual Key for the application, service, or user that will send traffic.
3. Configure the key with the provider, model access, department, budgets, and policies you want to enforce.
4. Copy the generated vk-... token. This token is the credential your application sends to Alephant Gateway.

Use separate Virtual Keys for different apps, environments, agents, or teams. This keeps logs, cost attribution, and policy enforcement clear.

Send Requests Through the Gateway

Use the Gateway base URL configured for your environment and pass the Virtual Key in the standard Authorization header.

$
curl https://alephant.io/v1/chat/completions \
>
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "model": "gpt-4o-mini",
>
    "messages": [
>
      { "role": "user", "content": "Write a one sentence status update." }
>
    ]
>
  }'

For gateway requests, use a Virtual Key. Do not send your provider API key to Alephant; the gateway injects the configured upstream credential after authenticating the Virtual Key.

Required Headers

Optional Tracking Headers

These headers help you attach business context to requests and improve logs, analytics, and debugging. Headers marked as gateway-only are not forwarded to the upstream model provider.

Example with request tracking:

$
curl https://alephant.io/v1/chat/completions \
>
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
>
  -H "Content-Type: application/json" \
>
  -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \
>
  -H "alephant-session-id: onboarding-demo" \
>
  -H "alephant-property-environment: production" \
>
  -H "alephant-property-customer-tier: enterprise" \
>
  -d '{
>
    "model": "gpt-4o-mini",
>
    "messages": [
>
      { "role": "user", "content": "Summarize this customer ticket." }
>
    ]
>
  }'

Cache Headers

Alephant supports gateway-side response caching. Cache headers are optional and are not sent to the upstream model provider.

Semantic cache and embedding headers are advanced gateway controls. Use them only when your workspace has semantic caching configured:

Logging and Privacy Controls

Some headers affect request logging behavior.

Avoid putting secrets or regulated personal data in custom alephant-property-* headers. They are intended for operational metadata that is safe to display in logs.

Client IP and Policy Evaluation

The gateway evaluates policies using request metadata, including headers that can be represented as UTF-8. For client IP:

• x-forwarded-for may be used by policy evaluation, with the leftmost IP treated as the client IP.
• Rate limiting only trusts x-forwarded-for when the direct peer is a configured trusted proxy. Otherwise, the direct peer IP is used.

Response Headers

Gateway responses may include Alephant-specific response metadata, such as:

Verify Requests

After sending a request through the gateway:

1. Open Logs to confirm the request was recorded.
2. Check Analytics for spend, requests, token usage, model, provider, and scoped metadata.
3. If a request fails, check the HTTP status and policy or budget configuration for the Virtual Key.

Common failures include invalid Virtual Key authentication, policy blocks, rate limits, unsupported models, or budget enforcement.