@memberjunction/api-keys-base

Metadata caching engine for MemberJunction's API key authorization system. This package provides cached, read-only access to API scopes, applications, and key bindings. It can be used on both client and server.

Architecture

graph TD
    subgraph "@memberjunction/api-keys-base"
        A[APIKeysEngineBase] --> B[Scope Cache]
        A --> C[Application Cache]
        A --> D[Key Binding Cache]
        B --> E["Lookup Maps<br/>(by path, by ID)"]
        C --> F["Lookup Maps<br/>(by name, by ID)"]
    end

    subgraph "Data Sources"
        G["MJ: API Scopes"]
        H["MJ: API Applications"]
        I["MJ: API Application Scopes"]
        J["MJ: API Key Applications"]
        K["MJ: API Key Scopes"]
    end

    G --> A
    H --> A
    I --> A
    J --> A
    K --> A

    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style B fill:#2d8659,stroke:#1a5c3a,color:#fff
    style C fill:#2d8659,stroke:#1a5c3a,color:#fff
    style D fill:#2d8659,stroke:#1a5c3a,color:#fff
    style E fill:#7c5295,stroke:#563a6b,color:#fff
    style F fill:#7c5295,stroke:#563a6b,color:#fff

Overview

The APIKeysEngineBase class extends MemberJunction's BaseEngine pattern to load and cache all API key-related metadata in memory. It is designed for fast, synchronous lookups after an initial asynchronous load.

Key capabilities:

• Cached access to API scopes, applications, application scopes, key applications, and key scopes
• Fast lookup maps for scopes (by path and ID) and applications (by name and ID)
• Hierarchical scope path resolution (e.g., entity:read, agent:execute)
• Application authorization checks for API keys
• UI configuration parsing for scope display

Installation

npm install @memberjunction/api-keys-base

Usage

Initializing the Engine

import { APIKeysEngineBase } from '@memberjunction/api-keys-base';

// Initialize with metadata load
await APIKeysEngineBase.Instance.Config(false, contextUser);

// Force refresh of cached data
await APIKeysEngineBase.Instance.Config(true, contextUser);

Accessing Cached Data

const engine = APIKeysEngineBase.Instance;

// All scopes
const allScopes = engine.Scopes;
const activeScopes = engine.ActiveScopes;

// All applications
const apps = engine.Applications;

// Scope lookups
const scope = engine.GetScopeByPath('entity:read');
const scopeById = engine.GetScopeById('scope-guid');

// Application lookups
const app = engine.GetApplicationByName('MCP Server');
const appById = engine.GetApplicationById('app-guid');

Checking Key Authorization

// Check if a key is authorized for a specific application
const isAuthorized = engine.IsKeyAuthorizedForApplication(apiKeyId, applicationId);

// Get all scope rules for a key
const keyScopes = engine.GetKeyScopesByKeyId(apiKeyId);

// Get application ceiling rules
const appScopes = engine.GetApplicationScopesByApplicationId(applicationId);

Parsing Scope UI Configuration

import { parseAPIScopeUIConfig } from '@memberjunction/api-keys-base';

const uiConfig = parseAPIScopeUIConfig(scope);
console.log(uiConfig.icon);  // e.g., 'fa-solid fa-database'
console.log(uiConfig.color); // e.g., '#6366f1'

API Reference

APIKeysEngineBase

| Member | Type | Description | |--------|------|-------------| | Instance | static getter | Singleton instance | | Config() | method | Load/refresh all metadata | | Scopes | getter | All API scopes | | ActiveScopes | getter | Only active scopes | | Applications | getter | All API applications | | ApplicationScopes | getter | All application scope ceilings | | KeyApplications | getter | All key-to-application bindings | | KeyScopes | getter | All key-level scope rules | | GetScopeByPath() | method | Look up active scope by full path | | GetScopeById() | method | Look up scope by ID | | GetApplicationByName() | method | Look up application by name (case-insensitive) | | GetApplicationById() | method | Look up application by ID | | GetApplicationScopesByApplicationId() | method | Get scope ceilings for an application | | GetApplicationScopeRules() | method | Get scope rules for an application + scope | | GetKeyApplicationsByKeyId() | method | Get application bindings for a key | | GetKeyScopesByKeyId() | method | Get scope rules for a key | | GetKeyScopeRules() | method | Get scope rules for a key + scope | | KeyHasApplicationBindings() | method | Check if a key has any application bindings | | IsKeyAuthorizedForApplication() | method | Check if a key is authorized for an application |

APIScopeUIConfig

interface APIScopeUIConfig {
    icon?: string;  // Font Awesome icon class
    color?: string; // Hex color code
}

Relationship to @memberjunction/api-keys

This package provides the metadata caching layer that can be used anywhere (client or server). The @memberjunction/api-keys package builds on top of this with server-side operations including key generation, validation, scope evaluation, and usage logging.

graph LR
    A["@memberjunction/api-keys-base<br/>(Metadata Caching)"] --> B["@memberjunction/api-keys<br/>(Server-side Engine)"]
    C["Client Code<br/>(Angular, etc.)"] --> A
    D["Server Code<br/>(MJAPI, MCP)"] --> B

    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style B fill:#2d8659,stroke:#1a5c3a,color:#fff
    style C fill:#b8762f,stroke:#8a5722,color:#fff
    style D fill:#b8762f,stroke:#8a5722,color:#fff

Dependencies

| Package | Purpose | |---------|---------| | @memberjunction/core | BaseEngine, UserInfo, IMetadataProvider | | @memberjunction/core-entities | Entity types (APIScopeEntity, etc.) | | @memberjunction/global | RegisterForStartup decorator |

License

ISC