> ## 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. |
| `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:

```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. 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 single-tenant and authentication-disabled configurations, Matcher uses `DEFAULT_TENANT_ID` and `DEFAULT_TENANT_SLUG`. In multi-tenant mode (`MULTI_TENANT_ENABLED=true`), `PLUGIN_AUTH_ENABLED` must also be true; Matcher rejects startup when `MULTI_TENANT_ENABLED=true` and `PLUGIN_AUTH_ENABLED=false`. The authenticated request must carry a valid `tenant_id` or `tenantId` claim. 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.

```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. Matcher encrypts stored actor 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/matcher/configuration/matcher-systemplane" horizontal>
  Review which runtime values can change without restarting Matcher.
</Card>

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