Plugin Management

Overview

The Plugin Management API provides endpoints for managing plugins that extend Authrim functionality. You can configure plugins for notification services, identity providers, and authenticators.

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/plugins`	List plugins
GET	`/api/admin/plugins/:id`	Get plugin details
GET	`/api/admin/plugins/:id/config`	Get plugin configuration
PUT	`/api/admin/plugins/:id/config`	Update plugin configuration
PUT	`/api/admin/plugins/:id/enable`	Enable plugin
PUT	`/api/admin/plugins/:id/disable`	Disable plugin
GET	`/api/admin/plugins/:id/health`	Get plugin health status
GET	`/api/admin/plugins/:id/schema`	Get plugin config JSON Schema

List Plugins

Retrieve a list of all registered plugins with their status.

Endpoint

GET /api/admin/plugins

Request Example

curl -X GET "https://{tenant-domain}/api/admin/plugins" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "plugins": [
    {
      "id": "notifier-console",
      "version": "1.0.0",
      "capabilities": ["notifier.email", "notifier.sms", "notifier.push"],
      "official": true,
      "meta": {
        "name": "Console Notifier",
        "description": "Logs notifications to console. For development and testing only.",
        "icon": "terminal",
        "category": "notification",
        "stability": "stable"
      },
      "source": {
        "type": "builtin",
        "identifier": "ar-lib-plugin/builtin/notifier/console"
      },
      "trustLevel": "official",
      "registeredAt": 1705881600000,
      "pluginId": "notifier-console",
      "enabled": true,
      "configSource": "default"
    },
    {
      "id": "notifier-resend",
      "version": "1.0.0",
      "capabilities": ["notifier.email"],
      "official": true,
      "meta": {
        "name": "Resend Email Notifier",
        "description": "Send transactional emails via Resend API",
        "icon": "mail",
        "category": "notification",
        "stability": "stable"
      },
      "source": {
        "type": "builtin",
        "identifier": "ar-lib-plugin/builtin/notifier/resend"
      },
      "trustLevel": "official",
      "registeredAt": 1705881600000,
      "pluginId": "notifier-resend",
      "enabled": true,
      "configSource": "kv"
    },
    {
      "id": "authenticator-totp",
      "version": "1.0.0",
      "capabilities": ["authenticator.totp"],
      "official": true,
      "meta": {
        "name": "TOTP Authenticator",
        "description": "Time-based One-Time Password authentication (RFC 6238)",
        "icon": "shield-check",
        "category": "authentication",
        "stability": "stable"
      },
      "source": {
        "type": "builtin",
        "identifier": "ar-lib-plugin/builtin/authenticator/totp"
      },
      "trustLevel": "official",
      "registeredAt": 1705881600000,
      "pluginId": "authenticator-totp",
      "enabled": true,
      "configSource": "default"
    }
  ],
  "total": 3
}

Get Plugin Details

Retrieve detailed information for a specified plugin including configuration and schema.

Endpoint

GET /api/admin/plugins/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Plugin ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/plugins/notifier-resend" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "plugin": {
    "id": "notifier-resend",
    "version": "1.0.0",
    "capabilities": ["notifier.email"],
    "official": true,
    "meta": {
      "name": "Resend Email Notifier",
      "description": "Send transactional emails via Resend API",
      "icon": "mail",
      "category": "notification",
      "author": {
        "name": "Authrim",
        "url": "https://authrim.com"
      },
      "license": "MIT",
      "tags": ["email", "transactional", "resend"],
      "stability": "stable",
      "documentationUrl": "https://resend.com/docs"
    },
    "source": {
      "type": "builtin",
      "identifier": "ar-lib-plugin/builtin/notifier/resend"
    },
    "trustLevel": "official",
    "registeredAt": 1705881600000
  },
  "status": {
    "pluginId": "notifier-resend",
    "enabled": true,
    "configSource": "kv",
    "lastHealthCheck": {
      "status": "healthy",
      "timestamp": 1705968000000,
      "message": "Resend API is reachable"
    }
  },
  "config": {
    "apiKey": "re_l****XYZ1",
    "defaultFrom": "[email protected]",
    "replyTo": "[email protected]"
  },
  "configSchema": {
    "type": "object",
    "properties": {
      "apiKey": {
        "type": "string",
        "description": "Resend API key"
      },
      "defaultFrom": {
        "type": "string",
        "description": "Default sender email address"
      },
      "replyTo": {
        "type": "string",
        "description": "Reply-to email address"
      }
    },
    "required": ["apiKey", "defaultFrom"]
  },
  "disclaimer": null
}

Get Plugin Configuration

Retrieve plugin configuration for global or tenant-specific settings.

Endpoint

GET /api/admin/plugins/:id/config

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Plugin ID

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	No	Tenant ID for tenant-specific configuration

Request Example

# Global configuration
curl -X GET "https://{tenant-domain}/api/admin/plugins/notifier-resend/config" \
  -H "Authorization: Bearer {token}"

# Tenant-specific configuration
curl -X GET "https://{tenant-domain}/api/admin/plugins/notifier-resend/config?tenant_id=tenant_123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "pluginId": "notifier-resend",
  "tenantId": null,
  "config": {
    "apiKey": "re_l****XYZ1",
    "defaultFrom": "[email protected]"
  },
  "source": "kv"
}

Update Plugin Configuration

Update plugin configuration. Sensitive fields are automatically encrypted before storage.

Endpoint

PUT /api/admin/plugins/:id/config

Request Body

Field	Type	Required	Description
`config`	object	Yes	Plugin configuration object
`tenant_id`	string	No	Tenant ID for tenant-specific override
`secret_fields`	string[]	No	Explicit list of fields to encrypt (auto-detected if not provided)

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/plugins/notifier-resend/config" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "apiKey": "re_new_api_key_here",
      "defaultFrom": "[email protected]",
      "replyTo": "[email protected]"
    }
  }'

Response Example

{
  "success": true,
  "pluginId": "notifier-resend",
  "tenantId": null,
  "config": {
    "apiKey": "re_n****here",
    "defaultFrom": "[email protected]",
    "replyTo": "[email protected]"
  },
  "encryptedFields": ["apiKey"]
}

Enable Plugin

Enable a plugin. Optionally specify a tenant ID for tenant-specific enablement.

Endpoint

PUT /api/admin/plugins/:id/enable

Request Body

Field	Type	Required	Description
`tenant_id`	string	No	Tenant ID for tenant-specific enablement

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/plugins/notifier-resend/enable" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response Example

{
  "success": true,
  "pluginId": "notifier-resend",
  "tenantId": null,
  "enabled": true
}

Disable Plugin

Disable a plugin. Optionally specify a tenant ID for tenant-specific disablement.

Endpoint

PUT /api/admin/plugins/:id/disable

Request Body

Field	Type	Required	Description
`tenant_id`	string	No	Tenant ID for tenant-specific disablement

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/plugins/notifier-resend/disable" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Response Example

{
  "success": true,
  "pluginId": "notifier-resend",
  "tenantId": null,
  "enabled": false
}

Get Plugin Health

Retrieve the health status of a plugin.

Endpoint

GET /api/admin/plugins/:id/health

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Plugin ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/plugins/notifier-resend/health" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "pluginId": "notifier-resend",
  "health": {
    "status": "healthy",
    "timestamp": 1705968000000,
    "message": "Resend API is reachable"
  }
}

Health Status Values

Status	Description
`healthy`	Plugin is functioning normally
`degraded`	Plugin is operational but experiencing issues
`unhealthy`	Plugin is not functioning
`unknown`	No health check data available

Get Plugin Schema

Retrieve the JSON Schema for a plugin’s configuration. Used by Admin UI for dynamic form generation.

Endpoint

GET /api/admin/plugins/:id/schema

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Plugin ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/plugins/authenticator-totp/schema" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "pluginId": "authenticator-totp",
  "version": "1.0.0",
  "schema": {
    "type": "object",
    "properties": {
      "issuer": {
        "type": "string",
        "default": "Authrim",
        "description": "Issuer name displayed in authenticator apps"
      },
      "algorithm": {
        "type": "string",
        "enum": ["sha1", "sha256", "sha512"],
        "default": "sha1",
        "description": "HMAC algorithm"
      },
      "digits": {
        "type": "number",
        "enum": [6, 8],
        "default": 6,
        "description": "Number of OTP digits"
      },
      "period": {
        "type": "number",
        "minimum": 15,
        "maximum": 120,
        "default": 30,
        "description": "Code refresh interval in seconds"
      },
      "window": {
        "type": "number",
        "minimum": 0,
        "maximum": 5,
        "default": 1,
        "description": "Time drift tolerance (±steps)"
      }
    }
  },
  "meta": {
    "name": "TOTP Authenticator",
    "description": "Time-based One-Time Password authentication (RFC 6238)",
    "category": "authentication"
  }
}

Plugin Categories

Category	Description
`notification`	Notification services (email, SMS, push)
`identity`	Identity providers (Google, SAML, OIDC)
`authentication`	Authenticators (TOTP, Passkey, OTP)
`flow`	Flow nodes (future extension)

Trust Levels

Plugin trust level is determined by the distribution source, not by metadata claims.

Trust Level	Source	Description
`official`	`builtin`	Included in ar-lib-plugin package
`official`	`npm @authrim/*`	Official npm scope
`community`	Other npm/local	Third-party plugins

Built-in Plugins

Plugin ID	Type	Description
`notifier-console`	Notifier	Console logger (development only)
`notifier-resend`	Notifier	Resend Email API
`authenticator-totp`	Authenticator	TOTP (RFC 6238)

Configuration Priority

Plugin configuration is resolved in the following order:

In-Memory Cache (60s TTL)
KV Storage (tenant-specific override)
KV Storage (global config)
Environment Variables (PLUGIN_{PLUGIN_ID}_CONFIG)
Schema Default Values

Multi-tenant Configuration

Tenant-specific plugin configurations override global settings:

plugins:config:{pluginId}                      # Global
plugins:config:{pluginId}:tenant:{tenantId}    # Tenant override
plugins:enabled:{pluginId}                     # Global enable/disable
plugins:enabled:{pluginId}:tenant:{tenantId}   # Tenant enable/disable

Use the tenant_id query parameter (GET) or request body field (PUT) to manage tenant-specific configurations.

Response Types

PluginRegistryEntry

{
  id: string;
  version: string;
  capabilities: string[];
  official: boolean;
  meta?: {
    name: string;
    description: string;
    icon?: string;
    category: 'notification' | 'identity' | 'authentication' | 'flow';
    documentationUrl?: string;
    author?: { name: string; email?: string; url?: string };
    license?: string;
    tags?: string[];
    stability?: 'stable' | 'beta' | 'alpha' | 'deprecated';
  };
  source: {
    type: 'builtin' | 'npm' | 'local' | 'unknown';
    identifier?: string;
    npmVersion?: string;
  };
  trustLevel: 'official' | 'community';
  registeredAt: number;
}

PluginStatus

{
  pluginId: string;
  enabled: boolean;
  configSource: 'kv' | 'env' | 'default';
  loadedAt?: number;
  lastHealthCheck?: {
    status: 'healthy' | 'degraded' | 'unhealthy';
    timestamp: number;
    message?: string;
  };
}

HealthStatus

{
  status: 'healthy' | 'degraded' | 'unhealthy';
  message?: string;
  checks?: Record<string, {
    status: 'pass' | 'warn' | 'fail';
    message?: string;
  }>;
  timestamp?: number;
}