Key Injection

Key injection is a security capability provided by the sandbox platform for protecting keys. Users can pre-configure injection rules and reference these rules when creating a sandbox. When an AI Agent inside the sandbox initiates a matching HTTPS request, the real key is automatically injected as the request leaves the sandbox. Code inside the sandbox cannot access the real key, ensuring key security.

How It Works

Sandbox (AI Agent) ─── HTTPS ──> Sandbox Platform ─── HTTPS ──> Upstream Service
  (No real key)                  (Inject real key)

Core Flow:

1. When creating a sandbox, pass injection rules via the injections field.
2. When code inside the sandbox initiates an HTTPS request, the platform automatically intercepts matching outbound traffic.
3. Injects or replaces authentication information according to the rules.
4. Forwards the request with the real key to the upstream service.

Security Guarantees:

• Keys are managed on the platform side; code inside the sandbox cannot read them directly.
• Only applies to matching outbound HTTPS requests.
• Only intercepts matched target domains; requests that do not match are passed through directly.
• Injection rules can be managed, reused, and audited independently.

Injection Rule Format

injections is an array. Each rule is differentiated by the type field, supporting the following types:

type	Description
id	Reference a saved injection rule
http	Custom HTTP injection (base_url + headers)
openai	OpenAI-compatible protocol; injects Authorization: Bearer <key>
anthropic	Anthropic protocol; injects x-api-key: <key>
gemini	Google Gemini protocol; injects x-goog-api-key: <key>
sufy	Sufy AI protocol; injects the key into the matching OpenAI or Anthropic auth header

Using Injection Rules in a Sandbox

id Type: Reference a Saved Rule

curl -X POST "$SUFY_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $SUFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "injections": [
      {
        "type": "id",
        "id": "rule-id-xxx"
      }
    ]
  }'

Referencing a saved rule is suitable for scenarios where rules need to be reused and centrally managed.

http Type: Custom HTTP Injection

base_url is used to match the target domain, and headers are the HTTP headers to inject.

curl -X POST "$SUFY_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $SUFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "injections": [
      {
        "type": "http",
        "base_url": "https://api.example.com",
        "headers": {
          "Authorization": "Bearer secret-token",
          "X-Custom-Header": "value"
        }
      }
    ]
  }'

Suitable for Azure OpenAI, custom services, or any scenario requiring manual header specification.

openai Type: OpenAI-Compatible Protocol

curl -X POST "$SUFY_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $SUFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "injections": [
      {
        "type": "openai",
        "api_key": "sk-real-openai-key"
      }
    ]
  }'

When base_url is not specified, it defaults to matching api.openai.com. To use a third-party service compatible with the OpenAI protocol, specify base_url:

{
  "type": "openai",
  "base_url": "https://api.deepseek.com",
  "api_key": "sk-deepseek-xxx"
}

anthropic Type: Anthropic Protocol

{
  "type": "anthropic",
  "api_key": "sk-ant-real-key"
}

When base_url is not specified, it defaults to matching api.anthropic.com.

gemini Type: Google Gemini Protocol

{
  "type": "gemini",
  "api_key": "AIza-real-key"
}

When base_url is not specified, it defaults to matching generativelanguage.googleapis.com.

sufy Type: Sufy AI Protocol

The Sufy AI gateway is compatible with both OpenAI and Anthropic protocols. The api_key is automatically injected based on the authentication header (Authorization or x-api-key) carried by the actual request, eliminating the need to distinguish between protocol types.

{
  "type": "sufy",
  "api_key": "your-sufy-ai-api-key"
}

When base_url is not specified, it defaults to matching the default Sufy AI API host.

Combining Multiple Rules

{
  "templateID": "base",
  "injections": [
    {
      "type": "openai",
      "api_key": "sk-real-openai-key"
    },
    {
      "type": "anthropic",
      "api_key": "sk-ant-real-key"
    },
    {
      "type": "http",
      "base_url": "https://my-resource.openai.azure.com",
      "headers": {
        "api-key": "your-azure-api-key"
      }
    }
  ]
}

Managing Injection Rules

Users can manage request injection rules via the Sufy Console or the Open API.

Create an Injection Rule

curl -X POST "$SUFY_SANDBOX_API_URL/injection-rules" \
  -H "Authorization: Sufy <SignedToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-api-key",
    "injection": {
      "type": "openai",
      "api_key": "sk-real-openai-key"
    }
  }'

List Injection Rules

curl -X GET "$SUFY_SANDBOX_API_URL/injection-rules" \
  -H "Authorization: Sufy <SignedToken>"

Get a Single Injection Rule

curl -X GET "$SUFY_SANDBOX_API_URL/injection-rules/$RULE_ID" \
  -H "Authorization: Sufy <SignedToken>"

Update an Injection Rule

curl -X PUT "$SUFY_SANDBOX_API_URL/injection-rules/$RULE_ID" \
  -H "Authorization: Sufy <SignedToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-api-key-v2",
    "injection": {
      "type": "openai",
      "api_key": "sk-new-openai-key"
    }
  }'

Delete an Injection Rule

curl -X DELETE "$SUFY_SANDBOX_API_URL/injection-rules/$RULE_ID" \
  -H "Authorization: Sufy <SignedToken>"

Field Descriptions

Injection Union

type	Required Fields	Optional Fields	Description
id	id	—	ID referencing a saved rule
http	base_url	headers	Custom HTTP injection
openai	api_key	base_url	OpenAI-compatible protocol, default host: api.openai.com
anthropic	api_key	base_url	Anthropic protocol, default host: api.anthropic.com
gemini	api_key	base_url	Google Gemini, default host: generativelanguage.googleapis.com
sufy	api_key	base_url	Sufy AI protocol, default host: api.sufyai.com

base_url

• Scheme can be omitted; defaults to https.
• The domain part is used for host matching.
• Wildcards (*, ?, +) are not supported.
• Explicit port numbers are not supported (only default HTTPS port is allowed).
• Paths are not supported.

headers (for http type)

• Maximum of 20 headers.
• Unconditionally set or overwritten on matching requests.

Limits

Limit Item	Maximum
Maximum injection rules per sandbox	20
Maximum headers for http type	20
Injection rule name length	64 characters
Header key/value length for http type	1000 bytes
api_key / base_url length	1000 bytes