> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For full documentation content, see https://developers.alephant.io/llms-full.txt. # Gateway Integration > Configure Virtual Keys and send provider-compatible requests through Alephant 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. ```bash 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 | Header | Usage | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Required. Use `Bearer `. The gateway authenticates the Virtual Key, then removes this header before forwarding upstream. | | `Content-Type` | Use `application/json` for JSON model requests. Provider-compatible content types are otherwise passed through. | ## 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. | Header | Usage | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-request-id` | Optional request correlation ID. If present and UUID-compatible, it can be used as the request log ID and policy request ID. Cache-hit responses may replace request correlation with `alephant-id` on the response. | | `alephant-session-id` | Gateway-only. Groups requests into a session for logs and analytics. | | `alephant-session-path` | Gateway-only. Optional session path. Prefer values beginning with `/`, such as `/checkout/retry`. | | `alephant-session-name` | Gateway-only. Optional human-readable session name. | | `alephant-property-*` | Gateway-only. Custom log properties. For example, `alephant-property-environment: production` or `alephant-property-feature: onboarding`. | | `alephant-prompt-id` | Gateway-only. Applies a stored prompt template before forwarding the request. The request body must be valid JSON. | | `alephant-forced-routing` | Advanced. Forces routing to a valid provider name when supported by the route. Use only for controlled testing or explicit failover workflows. | Example with request tracking: ```bash 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. | Header | Usage | | -------------------------------- | -------------------------------------------------------- | | `Alephant-Cache-Enabled` | Enables cache behavior when set to `true`. | | `Alephant-Cache-Read` | Allows reading from cache when set to `true`. | | `Alephant-Cache-Save` | Allows saving responses to cache when set to `true`. | | `Alephant-Cache-Bucket-Max-Size` | Optional bucket count. Valid range is 1-20. | | `Alephant-Cache-Seed` | Optional seed that participates in cache key derivation. | | `Alephant-Cache-Control` | Optional cache control, such as `max-age` or `s-maxage`. | Semantic cache and embedding headers are advanced gateway controls. Use them only when your workspace has semantic caching configured: | Header | Usage | | ----------------------------------- | ------------------------------------------------------------------- | | `Alephant-Embeddings-Model` | Embedding model used for semantic cache lookup. | | `Alephant-Embeddings-Key` | Embedding credential used by the gateway for semantic cache lookup. | | `Alephant-Cache-Semantic-Threshold` | Similarity threshold for semantic cache matching. | | `Alephant-Cache-Ttl` | Semantic cache TTL. | ## Logging and Privacy Controls Some headers affect request logging behavior. | Header | Usage | | ------------------------- | ------------------------------------------------------ | | `alephant-omit-request` | Omits request-side logging behavior when present. | | `alephant-omit-response` | Omits response-side logging behavior when present. | | `cf-ipcountry` | Country code source when traffic is behind Cloudflare. | | `x-alephant-country-code` | Country code fallback when `cf-ipcountry` is absent. | | `Referer` | Recorded as the request referrer. | 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: | Header | Usage | | --------------------------- | -------------------------------------------------------------------- | | `alephant-provider` | Provider selected by the gateway, when response headers are enabled. | | `alephant-provider-req-id` | Upstream provider request ID, when available and enabled. | | `alephant-cache` | Cache status for cache-enabled requests. | | `alephant-cache-bucket-idx` | Cache bucket index for cache hits. | | `alephant-cache-latency` | Cache lookup latency. | | `alephant-id` | Alephant request identifier, especially for cache-hit responses. | ## 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.