Skip to main content
Matcher implements comprehensive security controls to protect financial reconciliation data. This guide covers authentication, authorization, tenant isolation, encryption, and compliance features.

​
Overview

Matcher’s security architecture is built on several layers. Every API request passes through multiple security checkpoints before reaching your data.
1
First, TLS encrypts the connection.
2
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.
3
Finally, the system logs everything for audit purposes.

​
Layer protection

LayerProtection
TransportTLS 1.2+ encryption
AuthenticationJWT tokens via lib-auth
Tenant IsolationSchema-per-tenant PostgreSQL
AuthorizationRole-based access control
AuditImmutable append-only logs
StorageEncryption at rest

​
Authentication

Matcher uses the shared lib-auth library (v2) for authentication, supporting JWT-based access control with HMAC signing.

​
Configuration

Three environment variables control authentication:
VariableRequiredDescription
AUTH_ENABLEDYesEnable or disable authentication (true/false)
AUTH_SERVICE_ADDRESSWhen auth enabledAddress of the external authorization service
AUTH_JWT_SECRETWhen auth enabledShared secret for HMAC token signature verification
When AUTH_ENABLED=false (development only), Matcher uses a default tenant ID (11111111-1111-1111-1111-111111111111) and skips authorization checks.

​
JWT token structure

Matcher validates JWTs signed with HMAC algorithms (HS256, HS384, HS512). 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
}
ClaimRequiredDescription
tenant_id or tenantIdYesTenant UUID for schema isolation
tenant_slug or tenantSlugNoHuman-readable tenant identifier
subNoUser ID (used for audit logging)
expYesToken expiration time
nbfNoNot-before time (token is invalid before this)

​
Required headers

All API requests must include authentication: 
curl -X GET "https://api.matcher.example.com/v1/config/contexts" \
 -H "Authorization: Bearer $JWT_TOKEN"

​
Token validation

Matcher validates tokens on every request:
  1. Signature verification: Validates HMAC signature using the configured shared secret
  2. Expiration check: Rejects expired tokens (exp claim)
  3. Not-before check: Rejects tokens used before their nbf time
  4. Tenant extraction: Extracts tenant_id for schema isolation

​
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 pattern resource:sub-resource:action.

​
Permission structure

<resource>:<sub-resource>:<action>
Examples:
  • configuration:context:create — Create reconciliation contexts
  • matching:job:run — Execute matching jobs
  • exception:exception:resolve — Resolve exceptions

​
Complete permission list

Matcher defines six resource domains. Each endpoint requires a specific permission checked against the external authorization service.

​
Configuration

PermissionDescription
configuration:context:createCreate reconciliation contexts
configuration:context:readView contexts
configuration:context:updateUpdate contexts
configuration:context:deleteDelete contexts
configuration:source:createCreate data sources
configuration:source:readView source configuration
configuration:source:updateModify source settings
configuration:source:deleteRemove data sources
configuration:field-map:createCreate field mappings
configuration:field-map:readView field mappings
configuration:field-map:updateUpdate field mappings
configuration:field-map:deleteDelete field mappings
configuration:rule:createCreate match rules
configuration:rule:readView match rules
configuration:rule:updateUpdate match rules
configuration:rule:deleteDelete match rules
configuration:fee-schedule:createCreate fee schedules
configuration:fee-schedule:readView fee schedules
configuration:fee-schedule:updateUpdate fee schedules
configuration:fee-schedule:deleteDelete fee schedules
configuration:schedule:createCreate schedules
configuration:schedule:readView schedules
configuration:schedule:updateUpdate schedules
configuration:schedule:deleteDelete schedules

​
Ingestion

PermissionDescription
ingestion:import:createUpload transaction files
ingestion:job:readView import jobs and transaction details
ingestion:transaction:ignoreMark transactions as ignored
ingestion:transaction:searchSearch transactions

​
Matching

PermissionDescription
matching:job:runExecute match runs
matching:job:readView match run results and groups
matching:job:deleteDelete match groups (unmatch)
matching:adjustment:createCreate adjustment entries

​
Exception

PermissionDescription
exception:exception:readView exceptions and history
exception:exception:resolveForce match or adjust entries
exception:exception:dispatchDispatch exceptions to external systems
exception:callback:processProcess external webhook callbacks
exception:dispute:readView disputes
exception:dispute:writeCreate disputes, close disputes, submit evidence
exception:comment:writeAdd or delete comments on exceptions

​
Governance

PermissionDescription
governance:audit:readView audit logs
governance:archive:readView and download archives
governance:actor-mapping:readView actor mappings
governance:actor-mapping:writeCreate or update actor mappings
governance:actor-mapping:deleteDelete actor mappings

​
Reporting

PermissionDescription
reporting:dashboard:readAccess dashboard analytics and metrics
reporting:export:readView and export reports (matched, unmatched, summary, variance)
reporting:export-job:writeCreate and cancel export jobs
reporting:export-job:readView export job status and download exports

​
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 schema-per-tenant isolation in PostgreSQL, 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 sets the database connection to use that tenant’s schema via SET LOCAL search_path, so every query runs in complete isolation.
Even if a bug existed in the application layer, the database enforces separation. Schema isolation is applied per-transaction to prevent connection pool pollution.
Implementation details
  1. Tenant ID from JWT only: Never accepted from request parameters
  2. Automatic schema selection: Applied via auth.ApplyTenantSchema()
  3. Per-transaction isolation: Uses SET LOCAL search_path to scope each database transaction
  4. No cross-tenant access: Database enforces isolation

​
Isolation guarantees

GuaranteeImplementation
Data isolationSeparate PostgreSQL schemas
Query scopingSET LOCAL search_path per transaction
No tenant spoofingTenant from JWT only
Audit separationPer-tenant audit tables

​
Audit trail

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

​
Audited events

CategoryEvents
Data AccessView matches, view exceptions, export data
Data ModificationCreate match, resolve exception, update rules
ConfigurationCreate 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 $TOKEN"
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

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"
 }'
API Reference: Upsert actor mapping | Get actor mapping | Delete actor mapping

​
GDPR pseudonymization

To comply with right-to-erasure requests, pseudonymize an actor to replace their personal data with [REDACTED]. This action is irreversible.
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: List archives | Download archive

​
Data encryption

​
Encryption in transit

TLS encrypts all data transmitted to and from Matcher.
RequirementConfiguration
ProtocolTLS 1.2 or higher
Cipher suitesStrong ciphers only
CertificateValid CA-signed certificate
HSTSEnabled with 1-year max-age

​
Encryption at rest

Data TypeEncryption Method
DatabasePostgreSQL TDE (Transparent Data Encryption)
File storageAES-256 encryption
BackupsEncrypted before storage
SecretsVault with envelope encryption

​
SOX compliance

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

​
SOX control features

ControlMatcher Feature
Segregation of dutiesRBAC with granular permissions
Change managementAudit trail for all configuration changes
Access controlJWT authentication with role enforcement
Audit trailImmutable append-only logs
Data integrityTransaction checksums and validation

​
API security

​
Rate limiting

Some endpoints include additional rate limiting to protect against abuse:
Endpoint TypeRate Limited
Exception dispatchYes
Export endpointsYes
Callback processingYes

​
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 shared secret. The signature appears in the X-Signature-256 header, allowing receivers to verify authenticity.

​
Best practices

Grant users only the permissions they need. Start with minimal access and add permissions as needed.
Implement automatic rotation for service credentials and JWT secrets. Use short-lived tokens where possible.
Keep audit logs enabled and review them regularly. Set up alerts for suspicious activity.
Keep default rate limits enabled to protect against abuse. Adjust thresholds based on expected traffic patterns.
Conduct periodic access reviews. Remove access promptly when users change roles or leave.
Always validate HMAC-SHA256 signatures on webhook payloads to confirm they originate from Matcher.
Set up real-time monitoring and alerting for security events. Investigate anomalies promptly.

​
Next steps

Match rules

Configure matching rules securely.

Exception routing

Set up secure exception workflows.