Skip to main content
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: When AUTH_PROVIDER is unset, Matcher derives it from PLUGIN_AUTH_ENABLED. Enabled selects plugin-auth. Disabled selects disabled. The plugin-auth provider needs PLUGIN_AUTH_ADDRESS. Matcher rejects any other provider value, including the retired workos provider. Legacy AUTH_ENABLED and AUTH_SERVICE_ADDRESS remain aliases for the current PLUGIN_AUTH_* variables. Conflicting aliases prevent startup. When you enable authentication, protected API operations require a bearer token:
Do not maintain a static permission inventory in deployment runbooks. The route and provider policy define permission requirements, and they can evolve with the product. Use the API reference and the authorization-provider configuration when assigning roles.

​
Tenant isolation

In authentication-disabled and single-tenant configurations, Matcher uses DEFAULT_TENANT_ID and DEFAULT_TENANT_SLUG. In multi-tenant mode (MULTI_TENANT_ENABLED=true), the resolved provider must be plugin-auth, and the authenticated request must carry a valid tenant_id or tenantId claim. Matcher rejects startup when the resolved provider is disabled. 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. Configure the certificate and the key 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 stays read-only and reports the result for the records it inspected.
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, and Matcher never stores actor-mapping PII in plaintext. Matcher handles audit records separately, and they 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.