Default-Deny Permission System

GateFlow MCP uses a default-deny security model. Agents start with zero permissions and must be explicitly granted access to tools, models, and data.

Philosophy

Traditional: Allow everything, block bad things
GateFlow:    Block everything, allow good things

This approach ensures:

• No accidental data exposure
• No unexpected API costs
• Clear audit trail of granted permissions
• Compliance with least-privilege principles

How It Works

Agent Creation

When you create an agent, it has no permissions:

curl -X POST https://api.gateflow.ai/v1/mcp/agents \
  -H "Authorization: Bearer gw_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Agent"
  }'

This agent cannot:

• Call any tools
• Use any models
• Access any data

Granting Permissions

Explicitly grant what the agent needs:

curl -X PATCH https://api.gateflow.ai/v1/mcp/agents/agent_123 \
  -H "Authorization: Bearer gw_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "tools": ["llm/chat", "retrieval/search"],
      "models": ["gpt-4o-mini"],
      "data_classification": ["public", "internal"]
    }
  }'

Permission Types

Tool Permissions

Control which tools an agent can invoke:

permissions:
  tools:
    - llm/chat              # Can use chat completions
    - llm/embed             # Can create embeddings
    - retrieval/search      # Can search documents
    - retrieval/rerank      # Can rerank results
    # Cannot: voice/transcribe, voice/synthesize, etc.

Model Permissions

Restrict which models an agent can use:

permissions:
  models:
    - gpt-4o-mini           # Allowed
    - claude-3-haiku        # Allowed
    # Cannot use: gpt-4o, claude-3-opus (more expensive)

Data Classification

Limit access by data sensitivity:

permissions:
  data_classification:
    - public                # Can access public data
    - internal              # Can access internal data
    # Cannot access: confidential, restricted, top_secret

Rate Limits

Cap resource usage:

permissions:
  rate_limits:
    requests_per_minute: 60
    cost_per_session: 5.00
    cost_per_day: 100.00

Permission Inheritance

Permissions can be inherited from templates:

curl -X POST https://api.gateflow.ai/v1/mcp/agents \
  -H "Authorization: Bearer gw_prod_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "template": "customer-support",
    "permissions": {
      "tools": ["custom/ticket_lookup"]  # Add to template permissions
    }
  }'

Checking Permissions

Before Invocation

# Agent tries to call a tool
result = agent.tools.voice_transcribe(audio)

# If not permitted, raises:
# PermissionDenied: Agent 'support-bot' does not have permission
# for tool 'voice/transcribe'. Grant via dashboard or API.

Programmatic Check

can_transcribe = await agent.has_permission("voice/transcribe")
if not can_transcribe:
    return "I don't have permission to transcribe audio."

Audit Trail

All permission grants and denials are logged:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "agent_id": "agent_123",
  "action": "permission_denied",
  "tool": "voice/transcribe",
  "reason": "tool_not_in_allowlist"
}

Best Practices

1. Start Minimal

Begin with the fewest permissions needed:

# Good: Only what's needed
permissions:
  tools: ["llm/chat"]
  models: ["gpt-4o-mini"]

# Bad: Too broad
permissions:
  tools: ["*"]
  models: ["*"]

2. Use Templates

Create permission templates for common agent types:

templates:
  customer-support:
    tools: ["llm/chat", "retrieval/search"]
    models: ["gpt-4o-mini"]
    data_classification: ["public"]

  internal-assistant:
    tools: ["llm/chat", "retrieval/search", "retrieval/rerank"]
    models: ["gpt-4o"]
    data_classification: ["public", "internal"]

3. Regular Review

Periodically audit agent permissions:

curl https://api.gateflow.ai/v1/mcp/agents/permissions-report \
  -H "Authorization: Bearer gw_prod_..."

Next Steps

• Tool Permissions - Detailed tool permission guide
• Model Allowlists - Restrict models
• Data Classification - Data access controls