Guard Model Usage

Use this pattern when your application wants an explicit allow or deny decision before it calls a model. It is the cleanest fit for admin actions, premium features, or any flow where you want the application to own the final dispatch.

With SDK Provider Wrappers (Recommended)

If you’re using the provider wrappers, model governance is automatic: every model call made through the wrapper goes through Keel’s permit pipeline. Requests that carry tool definitions are refused, and tools your application runs are not governed by this call:


from keel_sdk.providers.openai import OpenAI
 
client = OpenAI()
# This call is automatically governed — Keel checks permits,
# enforces model policies, and records the audit trail
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize this document"}],
)

No manual permit creation needed. If the model is not allowed by your policy, the call raises a KeelError with the denial reason.

With Direct Client (Advanced)

Permit example

Hosted Keel requires a current X-Keel-Timestamp and a new X-Keel-Nonce on every permit-creation and execution request; without them it returns 401 request_not_fresh. See Request Freshness. The ai.generate action with generate.text matches the default policy a new personal project starts with; other action names need a policy rule that allows them.


curl -sS https://api.keelapi.com/v1/permits \
  -H "Authorization: Bearer keel_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "X-Keel-Timestamp: $(date +%s)" \
  -H "X-Keel-Nonce: $(openssl rand -hex 16)" \
  -d '{
    "project_id": "<project_uuid>",
    "idempotency_key": "recipe-guard-001",
    "subject": {
      "type": "user",
      "id": "usr_42"
    },
    "action": {
      "name": "ai.generate"
    },
    "resource": {
      "type": "request",
      "id": "req_guard_001",
      "attributes": {
        "provider": "openai",
        "model": "gpt-4o-mini",
        "operation": "generate.text",
        "modality": "text",
        "execution_mode": "sync",
        "estimated_input_tokens": 180,
        "estimated_output_tokens": 120,
        "max_output_tokens_requested": 160
      }
    }
  }'

Execution example

If the decision is allow, execute the provider call in your application or hand it back to Keel:


const response = await fetch('https://api.keelapi.com/v1/executions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer keel_sk_your_key_here',
    'X-Keel-Timestamp': String(Math.floor(Date.now() / 1000)),
    'X-Keel-Nonce': crypto.randomUUID(),
    'Content-Type': 'application/json',
    'Idempotency-Key': 'recipe-guard-exec-001'
  },
  body: JSON.stringify({
    operation: 'generate.text',
    messages: [
      { role: 'user', content: 'Draft a support reply in two sentences.' }
    ],
    routing: {
      provider: 'openai',
      model: 'gpt-4o-mini'
    },
    parameters: {
      max_output_tokens: 120
    }
  })
})
 
console.log(await response.json())