API Keys

API keys provide programmatic access to Atlas services for backend services and automation scripts.

---

What is an API Key?

An API key is a secret credential that:

• Authenticates backend services and scripts

• Associates requests with a specific project

• Inherits the project's team service policy

• Enables service-to-service communication

┌─────────────────────────────────────────────────────────────────────────────┐
│                        API KEY STRUCTURE                                     │
└─────────────────────────────────────────────────────────────────────────────┘

  API Key: sk-llm-api-a1b2c3d4e5f6g7h8i9j0...
           ├─┘├──────┘├──────────────────────┘
           │    │              │
           │    │              └── Random secret (32+ characters)
           │    │
           │    └── Project identifier (optional, for readability)
           │
           └── Prefix (sk- = secret key)

  Associated Data:
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ project_id: 5ac942ba-0290-48a7-be6e-7ea58cd40b68                        │
  │ team_id: ab2785b2-b5d0-4926-92fb-00aae5ec860a                           │
  │ org_id: 4047160a-abb2-497c-bf0c-3f4ab7cb0b16                            │
  │ created_by: [email protected]                                            │
  │ created_at: 2025-01-15T10:30:00Z                                        │
  │ expires_at: 2026-01-15T10:30:00Z (optional)                             │
  │ status: active                                                          │
  │ last_used: 2025-01-20T14:30:00Z                                         │
  └─────────────────────────────────────────────────────────────────────────┘

---

API Key Lifecycle

Creation

┌─────────────────────────────────────────────────────────────────────────────┐
│                        API KEY CREATION                                      │
└─────────────────────────────────────────────────────────────────────────────┘

  1. Admin goes to Admin → API Keys → Create

  2. Select project:
     ┌─────────────────────────────────────────────────────────────────────┐
     │ Project: LLM API                                                    │
     │ Team: Engineering (determines service access)                       │
     └─────────────────────────────────────────────────────────────────────┘

  3. Configure options:
     ┌─────────────────────────────────────────────────────────────────────┐
     │ Name: llm-api-production                                            │
     │ Description: Production API key for LLM service                     │
     │ Expires: 2026-01-15 (optional)                                      │
     └─────────────────────────────────────────────────────────────────────┘

  4. Key is generated:
     ┌─────────────────────────────────────────────────────────────────────┐
     │ ⚠️  IMPORTANT: Copy this key now. It will not be shown again!        │
     │                                                                     │
     │ sk-llm-api-a1b2c3d4e5f6g7h8i9j0klmnopqrstuvwxyz123456               │
     │                                                                     │
     │ [Copy to Clipboard]                                                 │
     └─────────────────────────────────────────────────────────────────────┘

Storage (Security)

⚠️ Critical: The API key is hashed before storage. The original key cannot be recovered.

┌─────────────────────────────────────────────────────────────────────────────┐
│                        KEY STORAGE                                           │
└─────────────────────────────────────────────────────────────────────────────┘

  Original Key (shown once):
  sk-llm-api-a1b2c3d4e5f6g7h8i9j0klmnopqrstuvwxyz123456

                    │
                    ▼ SHA-256 Hash

  Stored in Database:
  Document ID: 7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069

  Contents:
  {
    "project_id": "5ac942ba-...",
    "team_id": "ab2785b2-...",
    "org_id": "4047160a-...",
    "name": "llm-api-production",
    "created_by": "[email protected]",
    "created_at": "2025-01-15T10:30:00Z",
    "status": "active"
  }

  Note: Original key is NOT stored anywhere

Usage

import httpx
import os

# Load from environment (never hardcode!)
API_KEY = os.getenv("ATLAS_API_KEY")
AUTH_GUARD_URL = os.getenv("AUTH_GUARD_URL", "https://auth-gw.atlas.turing.com")

async def call_llm_service(prompt: str):
    """Call LLM service using API key"""
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{AUTH_GUARD_URL}/v1/llm/generate",
            headers={
                "X-Atlas-API-Key": API_KEY,
                "Content-Type": "application/json"
            },
            json={
                "prompt": prompt,
                "max_tokens": 1000
            }
        )
        response.raise_for_status()
        return response.json()

Revocation

When an API key is compromised or no longer needed:

┌─────────────────────────────────────────────────────────────────────────────┐
│                        KEY REVOCATION                                        │
└─────────────────────────────────────────────────────────────────────────────┘

  1. Admin goes to Admin → API Keys

  2. Find the key by name or project

  3. Click "Revoke" → Confirm

  4. Key status changes to "revoked"

  5. All requests using this key immediately fail with 401

  Note: Revocation is immediate, no cache delay

---

Authentication Flow

When a request includes an API key:

┌─────────────────────────────────────────────────────────────────────────────┐
│                     API KEY AUTHENTICATION FLOW                              │
└─────────────────────────────────────────────────────────────────────────────┘

  Request:
  POST /v1/llm/generate
  X-Atlas-API-Key: sk-llm-api-a1b2c3d4...
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 1. HASH THE KEY                                                          │
  │    Input: sk-llm-api-a1b2c3d4...                                         │
  │    Output: 7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200...    │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 2. LOOKUP IN DATABASE                                                    │
  │    Query: api_keys/{hash}                                                │
  │    ❌ Not found → 401 Unauthorized: Invalid API key                       │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 3. VALIDATE STATUS                                                       │
  │    Check: status == "active"                                             │
  │    ❌ status == "revoked" → 401 Unauthorized: API key revoked             │
  │    ❌ status == "expired" → 401 Unauthorized: API key expired             │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 4. CHECK EXPIRATION                                                      │
  │    If expires_at is set:                                                 │
  │    ❌ now > expires_at → 401 Unauthorized: API key expired                │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 5. LOAD CONTEXT                                                          │
  │    • Load project details                                                │
  │    • Load team details                                                   │
  │    • Load team service policy                                            │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 6. CHECK TEAM POLICY                                                     │
  │    Target service: "llm"                                                 │
  │    Team allowed_services: ["llm", "auto-rater", "oss"]                   │
  │    Is "llm" in allowed_services?                                         │
  │    ❌ NO → 403 Forbidden: Service not allowed for team                    │
  │    ✅ YES → Continue                                                      │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ 7. INJECT HEADERS & PROXY                                                │
  │    Add: X-Project-ID, X-Team-ID, X-Org-ID, etc.                          │
  │    Forward to backend service                                            │
  │    ✅ Success                                                             │
  └─────────────────────────────────────────────────────────────────────────┘

---

API Key vs JWT Token

Aspect	API Key	JWT Token
Use Case	Backend services, scripts	Web browsers, SPAs
Authentication	X-Atlas-API-Key header	Authorization: Bearer header
Expiration	Optional, can be years	24 hours
Revocation	Immediate	Wait for expiration
Context	Project-level	User-level with selected project
Permissions	Team policy only	Full RBAC
Refresh	Generate new key	Refresh token

---

Managing API Keys

Admin Dashboard

Access at: /admin/api-keys

Column	Description
Name	Key identifier
Project	Associated project
Team	Associated team
Status	active/revoked/expired
Created	Creation date
Expires	Expiration date (if set)
Last Used	Last usage timestamp

Actions

Action	Description
Create	Generate new API key
View	See key details (not the key itself)
Revoke	Immediately disable key
Delete	Remove key record

---

Security Best Practices

Storage

✅ Do	❌ Don't
Store in environment variables	Hardcode in source code
Use secrets manager	Commit to git
Encrypt at rest	Store in plain text files
Rotate regularly	Share keys between services

Access Control

✅ Do	❌ Don't
One key per service/environment	Share keys across services
Set expiration dates	Create keys that never expire
Revoke unused keys	Leave old keys active
Audit key usage	Ignore usage patterns

Operations

✅ Do	❌ Don't
Monitor for anomalies	Ignore usage spikes
Alert on failures	Ignore 401 errors
Rotate after incidents	Keep compromised keys
Document key ownership	Create orphan keys

---

Code Examples

Python

import httpx
import os
from typing import Optional

class AtlasClient:
    def __init__(
        self,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None
    ):
        self.api_key = api_key or os.getenv("ATLAS_API_KEY")
        self.base_url = base_url or os.getenv(
            "AUTH_GUARD_URL",
            "https://auth-gw.atlas.turing.com"
        )

        if not self.api_key:
            raise ValueError("ATLAS_API_KEY not set")

    async def call_service(
        self,
        service: str,
        endpoint: str,
        method: str = "POST",
        data: dict = None
    ):
        """Call an Atlas service through Auth Guard"""
        url = f"{self.base_url}/v1/{service}/{endpoint}"

        async with httpx.AsyncClient() as client:
            response = await client.request(
                method=method,
                url=url,
                headers={
                    "X-Atlas-API-Key": self.api_key,
                    "Content-Type": "application/json"
                },
                json=data
            )

            if response.status_code == 401:
                raise Exception("Invalid or expired API key")
            elif response.status_code == 403:
                raise Exception(f"Access denied: {response.json()}")

            response.raise_for_status()
            return response.json()

# Usage
client = AtlasClient()
result = await client.call_service(
    service="llm",
    endpoint="generate",
    data={"prompt": "Hello, world!"}
)

JavaScript/TypeScript

interface AtlasClientOptions {
  apiKey?: string;
  baseUrl?: string;
}

class AtlasClient {
  private apiKey: string;
  private baseUrl: string;

  constructor(options: AtlasClientOptions = {}) {
    this.apiKey = options.apiKey || process.env.ATLAS_API_KEY || '';
    this.baseUrl = options.baseUrl ||
      process.env.AUTH_GUARD_URL ||
      'https://auth-gw.atlas.turing.com';

    if (!this.apiKey) {
      throw new Error('ATLAS_API_KEY not set');
    }
  }

  async callService<T>(
    service: string,
    endpoint: string,
    options: {
      method?: string;
      data?: Record<string, unknown>;
    } = {}
  ): Promise<T> {
    const { method = 'POST', data } = options;
    const url = `${this.baseUrl}/v1/${service}/${endpoint}`;

    const response = await fetch(url, {
      method,
      headers: {
        'X-Atlas-API-Key': this.apiKey,
        'Content-Type': 'application/json',
      },
      body: data ? JSON.stringify(data) : undefined,
    });

    if (response.status === 401) {
      throw new Error('Invalid or expired API key');
    }

    if (response.status === 403) {
      const error = await response.json();
      throw new Error(`Access denied: ${JSON.stringify(error)}`);
    }

    if (!response.ok) {
      throw new Error(`Request failed: ${response.status}`);
    }

    return response.json();
  }
}

// Usage
const client = new AtlasClient();
const result = await client.callService('llm', 'generate', {
  data: { prompt: 'Hello, world!' }
});

cURL

# Set environment variable
export ATLAS_API_KEY="sk-your-api-key-here"

# Make request
curl -X POST "https://auth-gw.atlas.turing.com/v1/llm/generate" \
  -H "X-Atlas-API-Key: $ATLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, world!", "max_tokens": 100}'

---

Troubleshooting

"401 Unauthorized: Invalid API key"

Causes:

• Key doesn't exist

• Key is malformed

• Typo in key

Solutions:

1. Verify key is correct (check for extra spaces)

2. Generate new key if unsure

3. Check key format starts with sk-

"401 Unauthorized: API key revoked"

Causes:

• Admin revoked the key

• Key was compromised

Solutions:

1. Generate new API key

2. Update your service configuration

"401 Unauthorized: API key expired"

Causes:

• Key passed its expiration date

Solutions:

1. Generate new API key

2. Consider longer expiration or no expiration

"403 Forbidden: Service not allowed"

Causes:

• Key's team doesn't have access to the service

Solutions:

1. Check team's service policy

2. Add service to team's allowed_services

3. Use key from different team

"API key not working in production"

Causes:

• Using dev key in production

• Environment variable not set

• Key not deployed

Solutions:

1. Verify correct environment

2. Check deployment configuration

3. Verify key is for production project