# API Key Scoping & Security Roles

To enable continuous machine integration without sacrificing security, **Asterisk 2** implements an advanced API authorization framework. The system manages cryptographic tokens mapped to specific resource access arrays, providing granular control over automated client operations.

---

## Machine Authorization Pipeline

The layout below tracks the cryptographic validation sequence intercepting incoming API calls:

```mermaid
graph TD
    %% Ingress Client
    subgraph ClientTool["External Client Integration"]
        Request["REST Request Payload<br/>(with X-API-KEY Header)"]
    end

    %% Pipeline Interception
    subgraph ActionFilter["ASP.NET Core Authorization Filters"]
        Filter["ApiKeyFilter.cs Execution Block"]
        HashLook["Cryptographic Key Hash Lookup"]
    end

    %% Decision Node
    subgraph ScopeResolver["API Token Role Scoping"]
        RoleRO["ReadOnly Token Role<br/>(RAG Lookups, Document Reads)"]
        RoleRW["ReadWrite Token Role<br/>(Document Creation, Project Sync)"]
    end

    %% Target Core
    subgraph ExecTarget["Downstream Controller Modules"]
        ApiEndpoints["Documentation / Media Controllers"]
        McpGenerator["Admin Controller<br/>(Dynamic Tool Config Emitter)"]
    end

    %% Unauth
    Drop["Reject with HTTP 401 / 403"]

    %% Flow Lines
    Request ==> Filter
    Filter ==>|"Read X-API-KEY"| HashLook
    HashLook -->|"Hash Mismatch"| Drop
    HashLook ==>|"Hash Validated"| ScopeResolver
    
    ScopeResolver -->|"Scope == ReadOnly"| RoleRO
    ScopeResolver -->|"Scope == ReadWrite"| RoleRW
    
    RoleRO -->|"HTTP GET Allowed"| ApiEndpoints
    RoleRW ==>|"Full CRUD Action Allowed"| ApiEndpoints
    RoleRW ==>|"Generate Tool Configuration"| McpGenerator

    %% Custom CSS
    classDef toolClass fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#fff,rx:6px,ry:6px;
    classDef filterClass fill:#1e293b,stroke:#a855f7,stroke-width:2px,color:#fff,rx:6px,ry:6px;
    classDef scopeClass fill:#312e81,stroke:#ec4899,stroke-width:2px,color:#fff,rx:6px,ry:6px;
    classDef execClass fill:#065f46,stroke:#10b981,stroke-width:2px,color:#fff,rx:6px,ry:6px;
    classDef dropClass fill:#7f1d1d,stroke:#f87171,stroke-width:2px,color:#fff,rx:6px,ry:6px;

    class ClientTool,Request toolClass;
    class ActionFilter,Filter,HashLook filterClass;
    class ScopeResolver,RoleRO,RoleRW scopeClass;
    class ExecTarget,ApiEndpoints,McpGenerator execClass;
    class Drop dropClass;
```

---

## Token Lifecycle Management

### 1. Hash Validation Pipeline (`ApiKeyFilter.cs`)
Incoming REST requests clear standard HTTP cookie processing to undergo key validation. The filter extracts the `X-API-KEY` string and hashes it to query persistent storage tables. If a match fails, the pipeline immediately stops execution.

### 2. Role-Based Scoping Directives
API keys carry strict operational capabilities:
- **`ReadOnly` Tokens**: Granted solely for fetching document tree structures, querying RAG index content, and inspecting public project descriptions.
- **`ReadWrite` Tokens**: Fully authorized to create project structures, provision nested page structures, host uploaded binary assets, and delete stale document records.

### 3. Dynamic Tool Configuration Emitter
To streamline client tool integration, `AdminController.cs` provides a dedicated dynamic endpoint (`/api/Admin/mcp-config`). This endpoint parses runtime API configurations and outputs standardized client tool setup files mapped directly to verified token permissions.