Plugin Configuration

Configuration differs between bundled plugins and dynamic Runner installations. Do not use the KV merge model as a description of every plugin.

Bundled schemas

A bundled AuthrimPlugin provides a Zod schema. Use field descriptions for Admin UI help text and validate runtime configuration before use.

import { z } from 'zod';
const configSchema = z.object({
  apiKey: z.string().min(1).describe('Provider API key'),
  timeout: z.number().int().min(1000).max(30000).default(10000),
});

Schema conversion supports form generation, but a JSON Schema form is not a promise that every Zod refinement or union has an equivalent UI control. The Admin update handler explicitly validates built-in email and human-verification configurations.

Resolution and scope

For the bundled configuration path, bootstrap/environment values are combined with global KV configuration and then tenant overrides. Schema defaults apply during parsing. The relevant KV keys include:

• plugins:config:{pluginId}
• plugins:config:{pluginId}:tenant:{tenantId}
• plugins:enabled:{pluginId}
• plugins:enabled:{pluginId}:tenant:{tenantId}

Tenant-facing /api/admin/plugins/... uses the current tenant context. System-admin /api/admin/platform/plugins/... supports platform operations and explicit tenant selection. Those are authorization scopes, not interchangeable URL prefixes.

Secret handling

The Admin configuration handler detects secret fields by name or accepts secret_fields. Secret writes require PLUGIN_ENCRYPTION_KEY; the current helper does not fall back to KEY_MANAGER_SECRET. If encryption cannot be performed, the write is rejected with a missing-secret error. It does not store plaintext and continue.

Secret responses are masked. Preserve existing secrets through the supported UI/API update behavior rather than saving a displayed mask as a new credential. Recursive masking defaults to a depth limit of 20; deeper values can remain unmasked. Keep configuration shallow and validate the input structure rather than assuming arbitrary nesting is protected.

Dynamic Worker credentials

Dynamic installations use Runner-managed credentials and configuration versions. The Admin config endpoint accepts non-empty string credential values and calls replaceDynamicPluginCredentials with the expected version. This is replacement behavior, not the bundled arbitrary-object merge contract. The response does not echo the submitted credentials.

Credentials must match the approved manifest’s slots. The manifest specifies the exact destination host and header/bearer injection; the outbound gateway applies them for approved requests. The plugin is not given the parent Worker’s environment secrets.

Propagation and reset

Configuration changes can trigger provider projection/reprojection and cache invalidation. Check the resulting status before assuming every execution path has adopted a global change. The tenant config reset endpoint is DELETE /api/admin/plugins/:id/config; the effect differs by plugin backend.

Use Admin UI for configuration and test-email actions, and Deployment when changing the code or capability policy.