Security

Configure Matcher’s authentication, tenant isolation, transport posture, audit trail, and outbound-integration controls.

Matcher’s security behavior is deployment-configured. This page describes controls implemented by Matcher and the boundaries that remain the responsibility of your identity, network, and storage platforms. It is not a compliance certification.

Authentication and authorization

---

Matcher uses AUTH_PROVIDER to select authentication behavior:

Provider	Behavior
plugin-auth	Matcher delegates token trust and permission decisions to the configured plugin-auth service through lib-auth. Matcher holds no local JWT signing secret.
workos	Matcher verifies bearer-token signatures against WorkOS JWKS and evaluates its RBAC policy locally.
disabled	Matcher does not enforce bearer-token authentication or authorization.

AUTH_PROVIDER is derived from PLUGIN_AUTH_ENABLED when it is unset: enabled selects plugin-auth; disabled selects disabled. PLUGIN_AUTH_ADDRESS is required for the plugin-auth provider. The workos provider requires PLUGIN_AUTH_ENABLED=true and its WorkOS configuration. Legacy AUTH_ENABLED and AUTH_SERVICE_ADDRESS remain aliases for the current PLUGIN_AUTH_* variables; conflicting aliases prevent startup.

When authentication is enabled, protected API operations require a bearer token:

curl -X GET "https://api.matcher.example.com/v1/contexts" \
  -H "Authorization: Bearer $TOKEN"

Do not maintain a static permission inventory in deployment runbooks. Permission requirements are defined with the route and provider policy, and can evolve with the product. Use the API reference and the authorization-provider configuration when assigning roles.

Tenant isolation

---

In authentication-disabled configurations, Matcher uses DEFAULT_TENANT_ID and DEFAULT_TENANT_SLUG. With AUTH_PROVIDER=plugin-auth in single-tenant mode, an authenticated request uses a valid tenant_id or tenantId claim when present and falls back to the default identity only when that claim is absent; a malformed or invalid tenant ID is rejected. In multi-tenant mode (MULTI_TENANT_ENABLED=true), PLUGIN_AUTH_ENABLED must also be true and the authenticated request must carry a valid tenant_id or tenantId claim; Matcher rejects startup when MULTI_TENANT_ENABLED=true and PLUGIN_AUTH_ENABLED=false. AUTH_PROVIDER=workos currently resolves verified requests to DEFAULT_TENANT_ID; do not use it for tenant selection. Matcher does not accept a caller-controlled tenant selector from query parameters or request bodies.

Tenant Manager resolves a dedicated PostgreSQL pool for each tenant. The default tenant uses the root pool; Matcher does not use PostgreSQL SET search_path to switch tenant schema. Treat database credentials, network boundaries, and Tenant Manager configuration as part of the isolation boundary and verify them in your deployment.

Transport and infrastructure connections

---

Matcher can terminate TLS with SERVER_TLS_CERT_FILE and SERVER_TLS_KEY_FILE, or operate behind a trusted TLS-terminating proxy with TLS_TERMINATED_UPSTREAM=true. The certificate and key must be configured together.

TLS enforcement for dependencies is opt-in. Set the applicable flag to make startup fail when its connection configuration does not declare TLS:

• POSTGRES_TLS_REQUIRED
• POSTGRES_REPLICA_TLS_REQUIRED
• REDIS_TLS_REQUIRED
• RABBITMQ_TLS_REQUIRED
• OBJECT_STORAGE_TLS_REQUIRED

These flags protect the configured dependency connections; they do not replace ingress, network, certificate, or storage-security controls supplied by the deployment.

Audit trail and actor mappings

---

Matcher writes audit records for instrumented mutation workflows. Audit records are append-only and connected through a per-tenant, tamper-evident hash chain. The verification endpoint is read-only and reports the result for the records it inspected.

curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/verify" \
  -H "Authorization: Bearer $TOKEN"

Actor mappings can associate an opaque actor ID with a display name and email. Outside local, development, and test environments, set ACTOR_PII_ENCRYPTION_KEY to a base64-encoded 32-byte key before using them. When it is unset, actor-mapping operations return an encryptor-required error; Matcher never stores actor-mapping PII in plaintext. Audit records are handled separately and can retain the raw actorId, which can be an email address. With a key, Matcher encrypts stored actor-mapping PII and supports pseudonymize and delete operations. Determine retention, privacy, and legal obligations for your deployment separately.

Outbound integrations

---

Exception-dispatch connectors use SSRF controls that reject private, loopback, and link-local destinations by default. Review any configuration that permits private targets before using it in production.

Webhook and callback flows have their own verification and idempotency mechanisms. Configure shared secrets or trusted source IP ranges only through the relevant connector settings; do not rely on this page as a protocol contract. Use the API reference for the headers and payload contract of a specific integration.

Operational checklist

---

• Select and test the intended authentication provider before exposing Matcher.
• Enable authentication before enabling multi-tenant mode.
• Require TLS for each dependency that must not accept plaintext connections.
• Keep authorization roles least-privileged and review them in the identity provider.
• Monitor audit records and independently investigate a failed chain verification.
• Keep storage, backups, certificates, and secrets protected by deployment controls.

Next steps

---

Runtime configuration

Review which runtime values can change without restarting Matcher.

Governance

Manage actor mappings, audit logs, and archives.