Virtual Keys

Overview

Virtual Keys are the primary governance entity in DeepIntShield. Users and applications authenticate using the given headers to access virtual keys and get specific access permissions, budgets, and rate limits.

Allowed Headers:

• x-deepintshield-vk - Virtual key header, eg. sk-ds-*
• Authorization - Authorization header, eg. Bearer sk-ds-* (OpenAI style)
• x-api-key - API key header, eg. sk-ds-* (Anthropic style)
• x-goog-api-key - API key header, eg. sk-ds-* (Google Gemini style)

Note

Keep the key value out of source code and examples. Load it from a secret and send Authorization: Bearer $DEEPINTSHIELD_VIRTUAL_KEY or x-deepintshield-vk: $DEEPINTSHIELD_VIRTUAL_KEY.

Note

You can also use Authorization, x-api-key and x-goog-api-key headers to pass direct keys to the provider. Read more about it in Direct Key Bypass.

Key Features:

• Access Control - Model and provider filtering
• Cost Management - Independent budgets (checked along with team/customer budgets if attached)
• Rate Limiting - Token and request-based throttling (checked along with team/customer rate limits if attached)
• Key Restrictions - Limit VK to specific provider API keys (if configured, VK can only use those keys)
• Exclusive Attachment - Belongs to either one team OR one customer OR neither (mutually exclusive)
• Active/Inactive Status - Enable or disable access for subsequent requests; verify propagation across replicas during emergency revocation tests

Configuration

1. Go to Access & Credentials → Virtual API Keys
2. Click on Add Virtual Key button

Budget Configuration:

• Maximum Spend (USD): Dollar amount (e.g., 10.50)
• Reset Period: Every Minute, Every 5 Minutes, Every 15 Minutes, Every 30 Minutes, Hourly, Every 6 Hours, Daily, Weekly, or Monthly

Rate Limiting Configuration:

• Maximum Tokens: Max tokens per period
• Maximum Requests: Max requests per period
• Reset Period: Reset frequency for each limit

Entity Assignment (shown once a team or member exists):

• Assign to Team: Assign to existing team (mutually exclusive with member)
• Assign to Member: Assign to existing member, the console name for a customer (mutually exclusive with team)

3. Click Create

A Name and at least one provider under Provider Configurations are required before Create is enabled. You can configure provider access, budgets, rate limits, and team/customer associations all from this form. Note that a virtual key can belong to one team OR one customer, not both. Use the Allowed Keys field inside each provider under Provider Configurations to restrict the key to specific provider API keys, or leave it empty to allow access to all available keys.

User Groups

Note

Virtual keys are available on every plan, including the free Developer plan. Teams and Customers for grouping virtual keys under shared budgets require the Team plan or above.

Teams

Teams provide organizational grouping for virtual keys with department-level budget management. Teams can belong to one customer and have their own independent budget allocation.

Key Features:

• Organizational Structure - Group multiple virtual keys
• Independent Budgets - Department-level cost control (separate from customer budgets)
• Customer Association - Can belong to one customer (optional)
• Rate Limits - Optional token and request limits per period, shared by the team’s virtual keys

Configuration

1. Go to Access & Credentials → Teams

2. Click on Add Team button

Fill the form (team name, optional team members, budget, and rate limits) and click on Create Team button

3. Assign Virtual Keys to Team
   • Go to Virtual Keys page
   • Edit the virtual key and, under Entity Assignment, choose Assign to Team and select the team
   • Click on Update button

Customers

Customers represent the highest level in the governance hierarchy, typically corresponding to organizations or major business units. They provide top-level budget control and organizational structure.

Key Features:

• Top-Level Organization - Highest hierarchy level
• Independent Budgets - Organization-wide cost control (separate from team/VK budgets)
• Team Management - Contains multiple teams and direct VKs
• Rate Limits - Optional token and request limits per period, applied to every virtual key under the customer

Configuration

1. Go to Access & Credentials → Members (the console lists customers as members)

2. Click on Add Member button

Fill the form (member name, budget, and rate limits) and click on Create Member button

3. Assign Teams to Customer

   • Go to Teams page
   • Edit the team and add the member under Team Members
   • Click on Update Team button
   • Team Members records the association in the console. The customer’s own budget and rate limits are checked for a team’s virtual keys only when the team’s customer_id is set through the governance API (PUT /api/governance/teams/{team_id})

4. Assign Virtual Keys to Customer

   • Go to Virtual Keys page
   • Edit the virtual key and, under Entity Assignment, choose Assign to Member and select the member
   • Click on Update button

Features

• Budget and Limits - Enterprise-grade budget management and cost control and rate limiting using virtual keys
• Routing - Route requests to the appropriate providers/models and restrict api keys using virtual keys
• MCP Tool Filtering - Manage MCP clients/tools for virtual keys

Usage

Making Virtual Keys Mandatory

All governance-enabled requests must include the virtual key header:

curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-deepintshield-vk: sk-ds-engineering-main" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

By default governance is optional, meaning that if the virtual key header is not present, the request will be allowed but without any governance checks/routing. But you can make it mandatory by enforcing the virtual key header.

1. Open Security Settings (the /workspace/config/security page)

2. Turn on the Enforce Virtual Keys on Inference toggle and click Save Changes

When the governance header is enforced, the request will be rejected if the x-deepintshield-vk header is not present.

Authentication and Virtual Keys

Virtual keys and HTTP authentication are independent layers that can work together:

Layer	Purpose	Headers
Authentication	Validates user identity	Authorization: Basic/Bearer <credentials>
Virtual Keys	Request routing and governance	x-deepintshield-vk, Authorization1, x-api-key, x-goog-api-key

When disable_auth_on_inference: true (auth disabled):

Virtual keys can be passed via any supported header without additional authentication:

# Using x-deepintshield-vk header
curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "x-deepintshield-vk: sk-ds-your-virtual-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [...]}'

# Using Authorization header (OpenAI style)
curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Bearer sk-ds-your-virtual-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [...]}'

When disable_auth_on_inference: false (auth enabled):

You must provide both authentication credentials AND the virtual key. Use x-deepintshield-vk for the virtual key since the Authorization header is used for authentication:

curl -X POST https://app.deepintshield.com/v1/chat/completions \
  -H "Authorization: Basic <base64-credentials>" \
  -H "x-deepintshield-vk: sk-ds-your-virtual-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [...]}'

Configuring disable_auth_on_inference:

1. Open Security Settings (the /workspace/config/security page)
2. Under Password protect the dashboard, toggle Disable authentication on inference calls to enable/disable, then click Save Changes

Error Responses

• Virtual Key Required (401)

{
  "error": {
    "type": "virtual_key_required",
    "message": "virtual key is required. Provide a virtual key via the x-deepintshield-vk header."
  }
}

• Virtual Key Blocked (403)

{
  "error": {
    "type": "virtual_key_blocked",
    "message": "Virtual key is inactive"
  }
}

• Rate Limit Exceeded (429)

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limits exceeded: [token limit exceeded (1500/1000, resets every 1h)]"
  }
}

• Token Limit Exceeded (429)

{
  "error": {
    "type": "token_limited",
    "message": "Rate limits exceeded: [token limit exceeded (1500/1000, resets every 1h)]"
  }
}

• Request Limit Exceeded (429)

{
  "error": {
    "type": "request_limited",
    "message": "Rate limits exceeded: [request limit exceeded (101/100, resets every 1m)]"
  }
}

• Budget Exceeded (402)

{
  "error": {
    "type": "budget_exceeded",
    "message": "Budget exceeded: VK budget exceeded: 105.50 > 100.00 dollars"
  }
}

• Model Not Allowed (403)

{
  "error": {
    "type": "model_blocked",
    "message": "Model 'gpt-4o' is not allowed for this virtual key"
  }
}

• Provider Not Allowed (403)

{
  "error": {
    "type": "provider_blocked",
    "message": "Provider 'anthropic' is not allowed for this virtual key"
  }
}

Footnotes

1. Authorization can carry virtual keys only when auth is disabled (disable_auth_on_inference: true). When auth is enabled, Authorization is consumed by authentication and cannot be used for virtual keys. ↩