Service Policies

Service policies control service-to-service (S2S) communication, defining which backend services can call which other services through Auth Guard.

---

Why Service Policies?

Backend services in the Atlas ecosystem are deployed in a private network (VPC). They cannot communicate directly with each other. All inter-service communication must go through Auth Guard.

This architecture provides:

• Centralized access control - One place to manage all S2S permissions

• Audit trail - All S2S calls are logged

• Security - Deny-by-default, explicit authorization required

• Rate limiting - Prevent runaway service calls

┌─────────────────────────────────────────────────────────────────────────────┐
│                     SERVICE-TO-SERVICE ARCHITECTURE                          │
└─────────────────────────────────────────────────────────────────────────────┘

  ┌─────────────┐         ┌─────────────┐         ┌─────────────┐
  │  CLI-Eval   │         │  Auto-Rater │         │     LLM     │
  │   Service   │         │   Service   │         │   Service   │
  └──────┬──────┘         └──────▲──────┘         └──────▲──────┘
         │                       │                       │
         │ ❌ Direct call        │                       │
         │    NOT ALLOWED        │                       │
         │                       │                       │
         │ ✅ Via Auth Guard     │                       │
         │                       │                       │
         ▼                       │                       │
  ┌──────────────────────────────┴───────────────────────┴────────────────────┐
  │                            AUTH GUARD                                      │
  │                                                                            │
  │  ┌──────────────────────────────────────────────────────────────────────┐ │
  │  │                      POLICY ENGINE                                    │ │
  │  │                                                                       │ │
  │  │  1. Receive request with X-Atlas-API-Key                              │ │
  │  │  2. Validate API key, extract service account                         │ │
  │  │  3. Lookup policy: cli-eval → auto-rater                              │ │
  │  │  4. Check endpoint is in allowed_endpoints                            │ │
  │  │  5. Apply rate limiting                                               │ │
  │  │  6. ✅ Proxy request OR ❌ Deny with 403                               │ │
  │  │                                                                       │ │
  │  └──────────────────────────────────────────────────────────────────────┘ │
  └───────────────────────────────────────────────────────────────────────────┘

---

Policy Structure

Each service policy defines a permission for one service to call another:

Policy Fields

Field	Description	Example
service_account_email	The calling service's identity	[email protected]
target_service	The service being called	auto-rater
allowed_endpoints	Which endpoints can be called	["evaluate", "get-results"]
rate_limit	Max requests per minute	1000
quota_multiplier	Quota adjustment factor	1.0
description	Human-readable description	CLI-Eval can call Auto-Rater
enabled	Whether policy is active	true

Example Policy

┌─────────────────────────────────────────────────────────────────────────────┐
│                        EXAMPLE POLICY                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  service_account_email: [email protected]             │
│  target_service: auto-rater                                                  │
│  allowed_endpoints: ["evaluate", "get-results", "batch/*"]                   │
│  rate_limit: 1000                                                            │
│  quota_multiplier: 1.0                                                       │
│  description: CLI-Eval service can call Auto-Rater evaluation endpoints      │
│  enabled: true                                                               │
│                                                                              │
│  This policy allows:                                                         │
│  ✅ POST /v1/auto-rater/evaluate                                              │
│  ✅ GET /v1/auto-rater/get-results                                            │
│  ✅ POST /v1/auto-rater/batch/process                                         │
│  ❌ DELETE /v1/auto-rater/admin/delete (not in allowed_endpoints)             │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

How S2S Authentication Works

Step 1: Service Gets API Key

Each service that needs to call other services must have an API key:

# Environment variables in service deployment
CLI_EVAL_API_KEY=sk-cli-eval-abc123...
AUTH_GUARD_URL=https://auth-gw.atlas.turing.com

Step 2: Service Makes Request

import httpx
import os

AUTH_GUARD_URL = os.getenv("AUTH_GUARD_URL")
API_KEY = os.getenv("CLI_EVAL_API_KEY")

async def call_auto_rater(content: str):
    """Call auto-rater through Auth Guard"""
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{AUTH_GUARD_URL}/v1/auto-rater/evaluate",
            headers={
                "X-Atlas-API-Key": API_KEY,
                "Content-Type": "application/json"
            },
            json={"content": content}
        )

        if response.status_code == 403:
            # Policy denied - check policy configuration
            raise Exception(f"S2S policy denied: {response.json()}")

        response.raise_for_status()
        return response.json()

Step 3: Auth Guard Validates

┌─────────────────────────────────────────────────────────────────────────────┐
│                     S2S VALIDATION FLOW                                      │
└─────────────────────────────────────────────────────────────────────────────┘

  Request: POST /v1/auto-rater/evaluate
  Header: X-Atlas-API-Key: sk-cli-eval-abc123...
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 1. API KEY VALIDATION                                                    │
  │    • Hash the API key (SHA-256)                                          │
  │    • Lookup in api_keys table                                            │
  │    • Verify key is active and not expired                                │
  │    ❌ Invalid → 401 Unauthorized                                          │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 2. EXTRACT SERVICE IDENTITY                                              │
  │    • Get service_account_email from API key record                       │
  │    • Example: [email protected]                   │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 3. POLICY LOOKUP                                                         │
  │    • Query service_policies table                                        │
  │    • WHERE service_account_email = 'cli-eval@...'                        │
  │    • AND target_service = 'auto-rater'                                   │
  │    • AND enabled = true                                                  │
  │    ❌ No policy found → 403 Forbidden: No policy                          │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 4. ENDPOINT CHECK                                                        │
  │    • Extract endpoint from URL: "evaluate"                               │
  │    • Check if endpoint matches allowed_endpoints                         │
  │    • Supports exact match and wildcards                                  │
  │    ❌ Endpoint not allowed → 403 Forbidden: Endpoint not allowed          │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 5. RATE LIMIT CHECK                                                      │
  │    • Check requests in current window                                    │
  │    • Apply rate_limit from policy                                        │
  │    ❌ Rate exceeded → 429 Too Many Requests                               │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 6. PROXY REQUEST                                                         │
  │    • Forward request to auto-rater backend                               │
  │    • Inject context headers                                              │
  │    • Log the S2S call                                                    │
  │    ✅ Success                                                             │
  └─────────────────────────────────────────────────────────────────────────┘

---

Endpoint Patterns

The allowed_endpoints field supports different matching patterns:

Exact Match

{
  "allowed_endpoints": ["evaluate", "get-results", "status"]
}

Request	Match?
/v1/auto-rater/evaluate	✅ Yes
/v1/auto-rater/get-results	✅ Yes
/v1/auto-rater/status	✅ Yes
/v1/auto-rater/delete	❌ No
/v1/auto-rater/evaluate/batch	❌ No

Wildcard Match

{
  "allowed_endpoints": ["*"]
}

Request	Match?
Any endpoint	✅ Yes

Prefix Match

{
  "allowed_endpoints": ["batch/*", "admin/read-*"]
}

Request	Match?
/v1/service/batch/process	✅ Yes
/v1/service/batch/status	✅ Yes
/v1/service/admin/read-config	✅ Yes
/v1/service/admin/read-users	✅ Yes
/v1/service/admin/delete	❌ No
/v1/service/other	❌ No

---

Common Policy Patterns

Full Access

Allow service to call any endpoint:

service_account_email: [email protected]
target_service: llm
allowed_endpoints: ["*"]
description: Admin service has full LLM access

Read-Only Access

Allow only read operations:

service_account_email: [email protected]
target_service: analytics
allowed_endpoints: ["get-*", "list-*", "export"]
description: Reporting service can only read analytics data

Specific Operations

Allow only certain operations:

service_account_email: [email protected]
target_service: auto-rater
allowed_endpoints: ["evaluate", "get-results"]
description: CLI-Eval can only use evaluation endpoints

Batch Operations

Allow batch endpoints only:

service_account_email: [email protected]
target_service: llm
allowed_endpoints: ["batch/*"]
description: Batch processor can only use batch endpoints

---

Admin Dashboard

Access policy management at: /admin/policies

Policy List View

Column	Description
Caller	Service account email
Target	Target service name
Endpoints	Allowed endpoint patterns
Rate Limit	Requests per minute
Status	enabled/disabled

Policy Actions

Action	Description
Create	Add new S2S policy
Edit	Modify policy configuration
Enable/Disable	Toggle policy
Delete	Remove policy
Reload Cache	Force policy cache refresh

---

Setting Up S2S Communication

Step-by-Step Guide

1. Create API Key for Calling Service

   Go to Admin → API Keys → Create
   Name: cli-eval-to-auto-rater
   Project: cli-eval-project

2. Note the Service Account

   The API key is associated with:
   [email protected]

3. Create Service Policy

   Go to Admin → Policies → Create
   Service Account: [email protected]
   Target Service: auto-rater
   Allowed Endpoints: ["evaluate", "get-results"]
   Rate Limit: 1000

4. Configure Calling Service

   # In cli-eval deployment
   CLI_EVAL_API_KEY=sk-abc123...
   AUTH_GUARD_URL=https://auth-gw.atlas.turing.com

5. Test the Connection

   # In cli-eval code
   response = await call_auto_rater("test content")

---

Best Practices

Policy Design

Practice	Reason
Least privilege	Only allow needed endpoints
Specific patterns	Avoid * when possible
Document purpose	Clear descriptions
Regular audits	Review quarterly

Security

Practice	Reason
Rotate API keys	Security hygiene
Monitor S2S calls	Detect anomalies
Disable unused	Reduce attack surface
Alert on failures	Catch misconfigurations

Operations

Practice	Reason
Disable before delete	Safe testing
Test in dev first	Validate configuration
Use rate limits	Prevent runaway calls
Log everything	Audit trail

---

Troubleshooting

"403 Forbidden: No policy found"

Cause: No policy exists for the caller → target combination.

Solution:

1. Verify service_account_email is exactly correct

2. Verify target_service matches route name

3. Create policy if missing

"403 Forbidden: Endpoint not allowed"

Cause: Policy exists but endpoint isn't in allowed_endpoints.

Solution:

1. Check exact endpoint being called

2. Add endpoint to allowed_endpoints

3. Use wildcard if appropriate

"403 Forbidden: Policy disabled"

Cause: Policy exists but enabled: false.

Solution:

1. Enable the policy in dashboard

2. Or create new enabled policy

"429 Too Many Requests"

Cause: Service exceeded rate limit.

Solution:

1. Increase rate_limit in policy

2. Implement backoff in calling service

3. Optimize call patterns

"Policy changes not taking effect"

Cause: Policy cache not refreshed.

Solution:

1. Click "Reload Policies" in dashboard

2. Wait 30 seconds for propagation

3. Restart Auth Guard if urgent