Virtual API Keys

            Provider
               ↓
     Global LLM Collection
               ↓
    Workspace LLM Collection
        ├──────────────┐
        ▼              ▼
  Direct Model    Deployment
        \              /
         \            /
          ▼          ▼
         Virtual API Key       ← You are here
               ↓
        Gateway Request

Virtual API Keys (prefixed with vk_...) are the primary credentials used by client applications to authenticate requests against Infralo's OpenAI-compatible gateway.

Instead of distributing actual provider keys (like OpenAI, Anthropic, or Azure keys) to development teams or services, Infralo generates scoped virtual keys. The gateway verifies the virtual key, resolves its permissions, and forwards requests using the underlying encrypted credentials stored in the Global Collection.

Authentication Flow

When a request reaches the Infralo gateway:

1. The Virtual API Key is validated.
2. The associated workspace is resolved.
3. Permission scopes are evaluated.
4. The gateway verifies that the Virtual API Key is authorized to access the requested model or deployment.
5. The request is forwarded using the provider credentials stored in the Global LLM Collection.

Permission Scoping

Every Virtual API Key can be locked down using fine-grained permissions. When generating a key, you configure access levels across three main scopes:

1. Model Scope (LLMs)

Controls which models in the Workspace LLM Collection the key can access.

• Allow All: Key can access any whitelisted and enabled model in the workspace.
• Limit to Custom: Restricts the key to specific, selected model aliases (e.g., only gpt-4o-prod).
• Deny All: Block direct access to individual models (useful if you want to force applications to route through virtual Deployments instead).

2. Deployment Scope

Controls which virtual Deployments the key can invoke.

• Allow All: Key can access any deployment configured in the workspace.
• Limit to Custom: Restricts the key to specific virtual deployments (e.g., only customer-support-lb).
• Deny All: Blocks access to all deployments, restricting the key to direct model calls.

3. Endpoint Scope

Controls which gateway API routes are authorized for the key.

• Allow All: Key can call any supported endpoint.
• Limit to Custom: Restricts the key to specific routes. Supported routes include:
  • chat (Chat Completions: /chat/completions)
  • embeddings (Vector generation: /embeddings)
  • responses (Analytics & responses views)
  • models (Querying available models list)
• Deny All: Disables all endpoint access for the key.

Permission Evaluation Order

When evaluating permissions, Infralo follows a sequential pipeline to authorize incoming requests:

Virtual API Key
       │
       ▼
Endpoint Permission
       │
       ▼
Model / Deployment Permission
       │
       ▼
Gateway Routing

Security

Infralo incorporates enterprise-grade security practices to protect your gateway credentials:

Write-Once Visibility

When a Virtual API Key is generated, the raw key (e.g. vk_your_workspace_api_key_token) is displayed only once in the user interface.

• Security: Virtual API Keys are securely hashed before storage and cannot be viewed again after creation.
• Key Hints: For identification in management tables, the UI displays a safe key hint, showing only the prefix and the first and last four characters of the token payload (e.g. vk_Ab1c****xYz9).

Lifecycle Management

Expiration Policies

To maintain hygiene and support compliance rotation schedules, keys can be configured with expiration limits:

• Presets: Never expire, 7 days, 30 days, 60 days, or 90 days.
• Custom: Specify a precise target date and time.
• Deactivation: If a key passes its expiration date, Infralo's gateway immediately rejects incoming requests with an HTTP 401 Unauthorized status.

Revoking Keys

Keys can be revoked immediately in the dashboard. Once revoked, all requests using the key are rejected with an HTTP 401 Unauthorized status. Revoked keys take effect immediately and do not require gateway restarts or configuration reloads.

Best Practices

To maintain a secure and robust integration with Infralo:

• One Key Per Application: Issue a separate Virtual API Key for each client application or microservice. This allows you to rotate or revoke access for a single service without breaking others.
• Enforce Least Privilege: Restrict endpoint scopes to only what is necessary (e.g., an embedding worker should only have access to the embeddings endpoint).
• Prefer Deployments Over Direct Models: Route production traffic through Deployments rather than targeting Model Aliases directly. This allows you to leverage load balancing, fallback routing, and runtime processing transparently.
• Rotate Keys Regularly: Establish a key rotation schedule (e.g., every 90 days) to mitigate risks of credential leaks.

Authenticating Requests

Client applications pass the virtual API key using standard HTTP headers. Infralo supports two formats:

Virtual API Keys are supported by all official OpenAI-compatible SDKs by configuring the gateway URL as the client's base_url.

1. Authorization Header (Bearer Token)

The standard method supported by OpenAI SDKs and HTTP clients:

Authorization: Bearer vk_your_workspace_api_key

2. Custom API Key Header

For clients requiring direct header injection:

x-api-key: vk_your_workspace_api_key