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:

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.