> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. |
| `disabled`    | Matcher does not enforce bearer-token authentication or authorization.                                                                                        |

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:

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/contexts" \
  -H "Authorization: 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.

```bash theme={null}
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, 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

***

<Card title="Runtime configuration" icon="sliders" href="/en/products/matcher/configuration/matcher-systemplane" horizontal>
  Review which runtime values can change without restarting Matcher.
</Card>

<Card title="Governance" icon="shield-halved" href="/en/products/matcher/reference/matcher-governance" horizontal>
  Manage actor mappings, audit logs, and archives.
</Card>