Security - Lerian

Matcher implements comprehensive security controls to protect financial reconciliation data. This guide covers authentication, authorization, tenant isolation, encryption, and compliance features. Financial reconciliation data is among the most sensitive in any organization — it touches transaction records, counterparty information, and regulatory obligations. Regulations such as SOC 2, PCI DSS, and local financial authority requirements mandate specific controls around access, encryption, and auditability. Matcher is designed with these requirements in mind, providing defense-in-depth security across every layer of the stack.

Overview

Matcher’s security architecture is built on several layers. Every API request passes through multiple security checkpoints before reaching your data.

First, TLS encrypts the connection.

Then authentication verifies who you are:

Tenant isolation ensures you only see your own data.
RBAC checks whether you’re allowed to perform the action.

Finally, the system logs everything for audit purposes.

Layer protection

Layer	Protection
Transport	TLS 1.2+ encryption
Authentication	JWT tokens via lib-auth
Tenant Isolation	Database-per-tenant PostgreSQL (pool-per-tenant)
Authorization	Role-based access control
Audit	Immutable append-only logs
Storage	Encryption at rest

Authentication

Matcher uses the shared lib-auth library for JWT-based access control. Matcher delegates all cryptographic JWT validation to an external auth provider and holds no local JWT secret of its own.

Configuration

These environment variables control authentication:

Variable	Required	Description
`PLUGIN_AUTH_ENABLED`	Yes	Enable or disable authorization enforcement (`true`/`false`; default `false`)
`PLUGIN_AUTH_ADDRESS`	When auth enabled	Address of the external `plugin-auth` service
`AUTH_PROVIDER`	No	Validation provider: `plugin-auth`, `workos`, or `disabled`. When unset, it is derived from `PLUGIN_AUTH_ENABLED`

AUTH_ENABLED and AUTH_SERVICE_ADDRESS are accepted as legacy aliases for PLUGIN_AUTH_ENABLED and PLUGIN_AUTH_ADDRESS. Setting both an alias and its current form to conflicting values is rejected at boot.

When PLUGIN_AUTH_ENABLED=false (development only), Matcher uses a default tenant ID (11111111-1111-1111-1111-111111111111) and skips authorization checks.

JWT token structure

With AUTH_PROVIDER=plugin-auth, cryptographic validation is delegated to the plugin-auth service; with AUTH_PROVIDER=workos, Matcher verifies WorkOS access-token JWTs locally against the cached JWKS. Either way, the token must include tenant identification claims:

{
  "sub": "user_123",
  "tenant_id": "11111111-1111-1111-1111-111111111111",
  "tenant_slug": "acme-corp",
  "iat": 1705749600,
  "exp": 1705753200,
  "nbf": 1705749600
}

Claim	Required	Description
`tenant_id` or `tenantId`	Yes	Tenant UUID for tenant isolation
`tenant_slug` or `tenantSlug`	No	Human-readable tenant identifier
`sub`	No	User ID (used for audit logging)
`exp`	Yes	Token expiration time
`nbf`	No	Not-before time (token is invalid before this)

Required headers

All API requests must include authentication:

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

Token validation

Matcher validates tokens on every request:

Signature verification: Delegated to the configured auth provider (plugin-auth service, or WorkOS JWKS) — Matcher holds no local signing secret
Expiration check: Rejects expired tokens (exp claim)
Not-before check: Rejects tokens used before their nbf time
Tenant extraction: Extracts tenant_id to resolve the tenant’s database pool

Authorization (RBAC)

Role-based access control protects all API endpoints. Matcher delegates authorization to an external auth service via lib-auth. Permissions are granular and follow the two-part pattern resource:action.

Permission structure

<resource>:<action>

Resources are flat product nouns (plural) with no domain prefix and no sub-resource segment. Actions are verbs describing the operation performed against the noun. Examples:

contexts:create — Create reconciliation contexts
match-runs:run — Execute match runs
exceptions:resolve — Resolve exceptions

Complete permission list

Matcher defines a flat set of roughly 35 resources — there is no grouping into domains. Each endpoint requires a specific resource:action permission checked against the external authorization service. The tables below are grouped only for readability; the slugs themselves carry no domain qualifier.

Configuration

Permission	Description
`contexts:create`	Create reconciliation contexts
`contexts:read`	View contexts
`contexts:update`	Update contexts
`contexts:delete`	Archive (soft-delete) contexts
`contexts:clone`	Clone a context and its configuration
`sources:create`	Create data sources
`sources:read`	View source configuration
`sources:update`	Modify source settings
`sources:delete`	Remove data sources
`field-maps:create`	Create field mappings
`field-maps:read`	View field mappings
`field-maps:update`	Update field mappings
`field-maps:delete`	Delete field mappings
`rules:create`	Create match rules
`rules:read`	View match rules
`rules:update`	Update match rules
`rules:delete`	Delete match rules
`rules:reorder`	Reorder rule evaluation priority
`fee-schedules:create`	Create fee schedules
`fee-schedules:read`	View fee schedules
`fee-schedules:update`	Update fee schedules
`fee-schedules:delete`	Delete fee schedules
`fee-schedules:simulate`	Simulate fee schedule calculations
`fee-rules:create`	Create fee rules
`fee-rules:read`	View fee rules
`fee-rules:update`	Update fee rules
`fee-rules:delete`	Delete fee rules
`schedules:create`	Create schedules
`schedules:read`	View schedules
`schedules:update`	Update schedules
`schedules:delete`	Delete schedules

Ingestion

Permission	Description
`imports:create`	Upload transaction files
`imports:preview`	Preview import parsing before committing
`import-jobs:read`	View import jobs
`ingestion-transactions:search`	Search transactions
`ingestion-transactions:ignore`	Mark transactions as ignored
`extraction-reviews:create`	Enqueue AI document extractions and approve/reject reviews
`extraction-reviews:read`	View extraction reviews

Matching

Permission	Description
`match-runs:run`	Execute match runs
`match-runs:read`	View match run results
`match-groups:read`	View match groups
`match-groups:unmatch`	Unmatch match groups
`open-items:read`	View the carried-forward open-item residual ledger
`manual-matches:create`	Create manual matches
`adjustments:create`	Create adjustment entries
`rule-suggestions:create`	Produce and approve/reject rule suggestions
`rule-suggestions:read`	View rule suggestions

Exceptions and disputes

Permission	Description
`exceptions:read`	View exceptions and history
`exceptions:resolve`	Force match or adjust entries
`exceptions:assign`	Assign exceptions to users
`exceptions:dispatch`	Dispatch exceptions to external systems
`callback-credentials:read`	List callback credentials
`callback-credentials:write`	Mint or rotate callback credentials
`callback-credentials:delete`	Revoke callback credentials
`disputes:read`	View disputes
`disputes:write`	Create or update disputes
`disputes:close`	Close disputes
`disputes:submit-evidence`	Submit dispute evidence
`comments:read`	View comments
`comments:write`	Add comments on exceptions
`comments:delete`	Delete comments

Inbound external-system callbacks are authenticated by an opaque bearer token, not by RBAC, so there is no callbacks:process permission. The callback-credentials:* permissions gate only the JWT-protected surface that mints, rotates, lists, and revokes those tokens.

Reporting and analytics

Permission	Description
`dashboards:read`	Access dashboard analytics and metrics
`reports:read`	View reports (matched, unmatched, summary, variance)
`reports:export`	Export reports
`reports:count`	Count report rows
`export-jobs:create`	Create export jobs
`export-jobs:read`	View export job status
`export-jobs:cancel`	Cancel export jobs
`export-jobs:download`	Download export files

Governance and privacy

Permission	Description
`audit-logs:read`	View audit logs
`archives:read`	View archives
`archives:download`	Download archives
`actor-mappings:read`	View actor mappings
`actor-mappings:write`	Create or update actor mappings
`actor-mappings:delete`	Delete actor mappings
`actor-mappings:pseudonymize`	Pseudonymize actors (GDPR right-to-erasure)
`actor-mappings:deanonymize`	Reveal pseudonymized actor identities

Discovery

Permission	Description
`discovery-status:read`	View discovery status
`discovery-connections:read`	View discovery connections
`discovery-connections:create`	Create discovery connections
`discovery-connections:update`	Update discovery connections
`discovery-connections:write`	Write discovery connection data
`discovery-connections:delete`	Delete discovery connections
`discovery-connections:test`	Test discovery connections
`discovery-connections:extract`	Trigger discovery extraction
`discovery-extractions:read`	View discovery extractions
`discovery-extractions:poll`	Poll discovery extraction status. Seeded but not currently enforced on any endpoint — extraction reads are gated by `discovery-extractions:read`
`discovery-refresh:execute`	Execute discovery refresh

System

Permission	Description
`system-runtime-config:admin`	Administer system runtime configuration
`streaming-manifest:read`	Read the streaming manifest

Role management

The external authorization service manages roles, not Matcher itself. Configure roles and their associated permissions in your identity provider or auth service. Matcher checks permissions on each request by calling the auth service with the required resource and action.

Tenant isolation

Matcher uses pool-per-tenant isolation in PostgreSQL: each tenant’s data lives in its own database, providing strong data separation between tenants.

How it works

When a request arrives, Matcher extracts the tenant ID from the JWT token (never from query parameters or headers you control). It then resolves the dedicated connection pool for that tenant’s database, so every query runs against that tenant’s own database in complete isolation. There is no shared-schema switching — no SET search_path.

Because each tenant’s data lives in a physically separate database, a bug in the application layer still cannot reach another tenant’s data.

Implementation details

Tenant ID from JWT only: Never accepted from request parameters
Automatic pool resolution: The tenant’s database connection pool is resolved from context
Physical isolation: Each tenant’s queries run against its own database, not a shared one
No cross-tenant access: Physically separate databases enforce isolation

Isolation guarantees

Guarantee	Implementation
Data isolation	Separate PostgreSQL database per tenant
Query scoping	Per-tenant connection pool resolved from the JWT
No tenant spoofing	Tenant from JWT only
Audit separation	Per-tenant audit tables

Audit trail

Matcher records all actions in an immutable, append-only audit log for compliance and forensics.

Audited events

Category	Events
Data Access	View matches, view exceptions, export data
Data Modification	Create match, resolve exception, update rules
Configuration	Create context, modify source, change settings

Query audit logs

Use the governance audit log endpoints to retrieve audit records:

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

Verify audit log integrity

Audit logs form a tamper-evident hash chain per tenant. Use the verification endpoint to re-verify the chain — it returns a structured verdict (whether the chain is intact, how many records were verified, and the first broken sequence when a break is found). The check is strictly read-only and never mutates an audit record.

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

API Reference: List audit logs

Actor mappings and privacy

Actor mappings associate system identifiers (such as JWT sub claims) with human-readable display names and email addresses. This improves audit log readability without storing personal data in every log entry.

Manage actor mappings

The actor ID path parameter accepts up to 255 characters (matching the database column constraint). Leading and trailing whitespace is trimmed automatically. Values exceeding this limit are rejected with a 400 Bad Request error.

cURL

curl -X PUT "https://api.matcher.example.com/v1/governance/actor-mappings/user-abc-123" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "display_name": "John Doe",
   "email": "john.doe@company.com"
 }'

The upsert operation returns the persisted actor mapping directly in the response, so you can verify the saved values without a separate GET request.

API Reference:

To comply with right-to-erasure requests, pseudonymize an actor to replace their personal data with [REDACTED]. Pseudonymization is not reversible from the application; underlying records may be retained per compliance and audit policy.

cURL

curl -X POST "https://api.matcher.example.com/v1/governance/actor-mappings/user-abc-123/pseudonymize" \
 -H "Authorization: Bearer $TOKEN"

API Reference: Pseudonymize actor

Audit log archives

Historical audit logs are periodically compressed and moved to long-term storage. Use the archive endpoints to list and download archived data for compliance reviews.

cURL

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

API Reference:

Data encryption

Encryption in transit

TLS encrypts all data transmitted to and from Matcher.

Requirement	Configuration
Protocol	TLS 1.2 or higher
Cipher suites	Strong ciphers only
Certificate	Valid CA-signed certificate
HSTS	1-year max-age with preload, sent when `SERVER_TLS_CERT_FILE` is configured or `TLS_TERMINATED_UPSTREAM=true`

Encryption at rest

Encryption at rest is a deployment-environment responsibility: in a BYOC deployment, your infrastructure — not Matcher itself — provides these controls. A production deployment should provide:

Data Type	Encryption Method
Database	PostgreSQL TDE (Transparent Data Encryption)
File storage	AES-256 encryption
Backups	Encrypted before storage
Secrets	Vault with envelope encryption

SOX compliance

Matcher maintains records for SOX (Sarbanes-Oxley) audit requirements.

SOX control features

Control	Matcher Feature
Segregation of duties	RBAC with granular permissions
Change management	Audit trail for all configuration changes
Access control	JWT authentication with role enforcement
Audit trail	Immutable append-only logs
Data integrity	Transaction checksums and validation

API security

Rate limiting

Some endpoints include additional rate limiting to protect against abuse:

Endpoint Type	Rate Limited
Exception dispatch	Yes
Export endpoints	Yes
Callback processing	Yes

SSRF protection

Matcher blocks outbound HTTP requests to private IP ranges when dispatching exceptions to external systems. This prevents Server-Side Request Forgery (SSRF) attacks. Blocked ranges include 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, and IPv6 equivalents.

Webhook signature verification

Matcher signs outbound webhook payloads with HMAC-SHA256 using a per-target shared secret. The signature appears in the X-Signature-256 header, formatted as sha256=<hex-digest>, allowing receivers to verify authenticity. (Dispatch also sets an X-Idempotency-Key header for at-most-once delivery.)

Best practices

Use least privilege access

Grant users only the permissions they need. Start with minimal access and add permissions as needed.

Rotate credentials regularly

Implement automatic rotation for service credentials. Use short-lived tokens where possible.

Enable audit logging

Keep audit logs enabled and review them regularly. Set up alerts for suspicious activity.

Use rate limiting

Keep default rate limits enabled to protect against abuse. Adjust thresholds based on expected traffic patterns.

Review access regularly

Conduct periodic access reviews. Remove access promptly when users change roles or leave.

Verify webhook signatures

Always validate HMAC-SHA256 signatures on webhook payloads to confirm they originate from Matcher.

Monitor security events

Set up real-time monitoring and alerting for security events. Investigate anomalies promptly.

​Overview

​Layer protection

​Authentication

​Configuration

​JWT token structure

​Required headers

​Token validation

​Authorization (RBAC)

​Permission structure

​Complete permission list

​Configuration

​Ingestion

​Matching

​Exceptions and disputes

​Reporting and analytics

​Governance and privacy

​Discovery

​System

​Role management

​Tenant isolation

​How it works

​Isolation guarantees

​Audit trail

​Audited events

​Query audit logs

​Verify audit log integrity

​Actor mappings and privacy

​Manage actor mappings

​GDPR pseudonymization

​Audit log archives

​Data encryption

​Encryption in transit

​Encryption at rest

​SOX compliance

​SOX control features

​API security

​Rate limiting

​SSRF protection

​Webhook signature verification

​Best practices

​Next steps

Match rules

Exception routing

Overview

Layer protection

Authentication

Configuration

JWT token structure

Required headers

Token validation

Authorization (RBAC)

Permission structure

Complete permission list

Configuration

Ingestion

Matching

Exceptions and disputes

Reporting and analytics

Governance and privacy

Discovery

System

Role management

Tenant isolation

How it works

Isolation guarantees

Audit trail

Audited events

Query audit logs

Verify audit log integrity

Actor mappings and privacy

Manage actor mappings

GDPR pseudonymization

Audit log archives

Data encryption

Encryption in transit

Encryption at rest

SOX compliance

SOX control features

API security

Rate limiting

SSRF protection

Webhook signature verification

Best practices

Next steps