> ## 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. # Integration guide > How to integrate your authorization system with Tracer for real-time transaction validation. This guide explains how to integrate external systems with Tracer, including the payload requirements, integration flow, and best practices for achieving optimal performance. ## Integration overview *** Tracer is designed to be called by **authorization systems** (payment gateways, workflow orchestrators, or transaction processors) that need real-time validation decisions. The integration follows a simple request-response pattern: **Key principle:** Tracer does not fetch external data during validation. Your system is responsible for providing all context needed for rule evaluation. *** ## Payload-Complete Pattern *** Tracer uses the **Payload-Complete Pattern**, which means all context required for validation must be included in the request. This design ensures: | Benefit | Description | | ----------------------- | ------------------------------------------------------------------- | | **Predictable latency** | No external calls during validation; response time stays under 80ms | | **Simplicity** | Single request contains everything needed for decision | | **Reliability** | No dependency on external services during validation | | **Flexibility** | Your system controls data freshness and enrichment logic | ### Your responsibilities As the integrating system, you are responsible for: 1. **Enriching the payload** with account, segment, portfolio, and merchant data before calling Tracer 2. **Providing accurate context** for rule and limit evaluation—Tracer cannot fetch missing data 3. **Handling the decision** (ALLOW, DENY, or REVIEW) appropriately in your workflow 4. **Implementing retry logic** if Tracer is temporarily unavailable 5. **Managing review workflows** when Tracer returns `REVIEW`—Tracer does not include case management Tracer validates what you send. If your payload is missing context (e.g., account status, segment membership), rules that depend on that data cannot evaluate correctly. Always ensure payloads are complete before submission. ### Tracer's responsibilities Tracer is responsible for: 1. **Evaluating rules** against the provided context 2. **Checking limits** against current usage 3. **Recording audit trail** for compliance 4. **Returning decision** with detailed information *** ## Integration flow *** Follow these steps to integrate your system with Tracer. ### Step 1: Prepare the transaction context Before calling Tracer, gather all relevant data from your systems: ### Step 2: Call Tracer API Send a POST request to `/v1/validations` with the complete transaction context including: * Transaction details (type, subType, amount, currency, timestamp) * Account information (required) * Optional: segment, portfolio, merchant, and custom metadata For complete payload structure and field details, see the [API reference](/en/reference/tracer/validate-transaction). ### Step 3: Handle the response Process the decision returned by Tracer: | Decision | Action | | -------- | ---------------------------------------------------------- | | `ALLOW` | Proceed with the transaction | | `DENY` | Reject the transaction; show reason to user if appropriate | | `REVIEW` | Queue for manual review in your review system | The response includes the `validationId` for audit trail correlation, details about which rules matched, and current limit usage information. ### Using metadata Metadata allows you to pass custom fields that your rules can evaluate. Use this for context like channel, device information, customer tier, or any business-specific attributes. Metadata keys must be alphanumeric with underscores only, maximum 64 characters. Maximum 50 entries per request. *** ## Request idempotency *** Validation requests are **idempotent** based on the `requestId` field. If you send the same `requestId` twice, Tracer returns the cached result from the first request instead of reprocessing. | Response code | Meaning | | ------------- | -------------------------------------------------- | | `201 Created` | New validation processed | | `200 OK` | Duplicate request detected; cached result returned | The response body is identical in both cases. Your client should handle both status codes as success. **Why it matters:** Network timeouts and retries can cause duplicate requests. Without idempotency, a retried request could double-count against limits or create duplicate audit records. The `requestId` ensures exactly-once processing semantics. **Idempotency contract:** * Same `requestId` → Same response (guaranteed) * Different `requestId` → Independent processing (even if transaction data is identical) Always generate a unique `requestId` (UUID) for each new transaction. Reusing a `requestId` from a previous transaction will return the old result, not process the new transaction. *** ## Authentication *** Tracer supports two authentication modes that can be used independently or combined. ### API key authentication The simplest option. Send your API key in the `X-API-Key` header with every request. | Environment variable | Description | | --------------------------------- | ---------------------------------------------------------------------- | | `API_KEY_ENABLED` | Enable API key authentication (default: `false`) | | `API_KEY` | The secret key value | | `API_KEY_ENABLED_ONLY_VALIDATION` | Use API key only for the `/v1/validations` endpoint (default: `false`) | ### Plugin authentication (Access Manager) For enterprise deployments, Tracer can delegate authentication to the [Lerian Access Manager](/platform/access-manager/auth-plugin). This enables centralized authentication across all Lerian services. | Environment variable | Description | | --------------------- | ---------------------------------------------------------- | | `PLUGIN_AUTH_ENABLED` | Enable plugin authentication (default: `false`) | | `PLUGIN_AUTH_ADDRESS` | URL of the auth service (default: `http://localhost:4000`) | ### Authentication priority When both modes are enabled, Tracer uses this priority: 1. If `PLUGIN_AUTH_ENABLED=true` and the endpoint is not flagged for API-key-only → Plugin auth 2. If `API_KEY_ENABLED=true` or the endpoint is flagged for API-key-only → API key auth Infrastructure endpoints (health checks, version probe, OpenAPI spec) bypass authentication and are not part of the public `/v1/*` API surface documented in this reference. The `/v1/validations` endpoint can be configured for API-key-only authentication via `API_KEY_ENABLED_ONLY_VALIDATION=true`. This is useful in high-throughput scenarios where plugin auth adds unacceptable latency. **This flag is incompatible with multi-tenant mode** (`MULTI_TENANT_ENABLED=true`) — the service fails to start with TRC-0327. ### Multi-tenant authentication When `MULTI_TENANT_ENABLED=true`, Tracer runs in multi-tenant mode and the authentication model changes: * **Plugin auth is required.** The service fails to start with TRC-0326 if `PLUGIN_AUTH_ENABLED=false`. * **Every `/v1/*` request must carry a JWT bearer token** issued by [Access Manager](/en/platform/access-manager/access-manager): `Authorization: Bearer `. * **`tenantId` is resolved from the JWT claim**, not from a header, path, body, metadata, or rule scope. There is no `X-Tenant-ID` header — passing the tenant identifier anywhere other than the token claim is unsupported and ignored. * Each tenant operates on its own PostgreSQL database. The tenant-specific connection is resolved by the platform's Tenant Manager service at request time. * **Public endpoints (`/health`, `/readyz`, `/version`, `/swagger/*`) stay unauthenticated** in multi-tenant mode too — the bearer-token requirement applies only to `/v1/*`. If the JWT is missing, malformed, or expired, the request returns HTTP 401 with `"code": "Unauthenticated"` (the same code used for missing API keys; no separate TRC code is emitted). If the multi-tenant deployment hits its per-instance tenant cap, requests for cold tenants return HTTP 503 with TRC-0335 and a `Retry-After` header. The client should back off and retry; the cap auto-resets as the LRU pool evicts cold tenants. See [Multi-tenancy](/en/multi-tenancy) for the platform-wide tenant model. *** ## Performance considerations *** Optimize your integration for low latency and high reliability. ### Timeout budget Tracer is designed to respond in under **80ms (p99)**. Configure your client timeout accordingly: | Configuration | Recommended value | | ------------------ | ----------------- | | Client timeout | 100ms | | Connection timeout | 50ms | | Read timeout | 100ms | ### Retry strategy Implement retry logic for transient failures: ``` On 5xx error or timeout: - Wait 10ms - Retry once - If still failing, apply fallback policy ``` Do not retry on 4xx errors—these indicate invalid requests that will fail again. For retries on 5xx/timeout, reuse the same requestId to take advantage of idempotency. ### Fallback behavior Decide what happens when Tracer is unavailable: | Strategy | When to use | | -------------------- | ------------------------------------------------------------- | | **Fail-open** | Allow transaction if Tracer is down (prioritize availability) | | **Fail-closed** | Deny transaction if Tracer is down (prioritize security) | | **Queue for review** | Queue transaction for manual review | Your choice depends on your risk tolerance and business requirements. *** ## Data freshness *** Since you control the payload enrichment, data freshness is your responsibility. Tracer trusts the data you provide and cannot detect stale information. | Data type | Freshness recommendation | Risk if stale | | -------------------- | ------------------------------------ | ------------------------------------------------- | | Account status | Real-time or near real-time | Transactions on suspended accounts may be allowed | | Segment membership | Can be cached (changes infrequently) | Wrong limits or rules may apply | | Portfolio assignment | Can be cached (changes infrequently) | Incorrect scope matching | | Merchant data | Can be cached with periodic refresh | Risk rules may not trigger correctly | Stale data leads to incorrect decisions. If an account was suspended but your cache shows it as active, Tracer will allow transactions that should be denied. Your enrichment layer is the source of truth for Tracer. *** ## Date and time format *** All datetime fields must use **RFC3339 format** with mandatory timezone: **Valid formats:** ``` 2026-01-30T10:30:00Z (UTC) 2026-01-30T10:30:00-03:00 (São Paulo timezone) 2026-01-30T00:00:00+00:00 (UTC explicit) ``` **Invalid formats:** ``` 2026-01-30 (date only - rejected) 2026-01-30T10:30:00 (missing timezone - rejected) ``` *** ## Integration checklist *** Before going to production, verify: * [ ] API Key is configured and secured * [ ] Each request includes a unique requestId (UUID) * [ ] Client handles both 201 and 200 responses as success * [ ] Client timeout is set to 100ms * [ ] Retry logic is implemented for 5xx errors * [ ] Fallback behavior is defined * [ ] All required fields are populated * [ ] Timestamps use RFC3339 format with timezone * [ ] Currency codes are uppercase ISO 4217 * [ ] Decision handling is implemented (ALLOW/DENY/REVIEW) * [ ] Validation IDs are logged for audit trail correlation *** ## Example integration (pseudocode) *** ```python theme={null} def validate_transaction(transaction): # Step 1: Enrich payload payload = { "requestId": generate_uuid(), "transactionType": transaction.type, "amount": transaction.amount, "currency": transaction.currency.upper(), "timestamp": now_rfc3339(), "account": get_account_context(transaction.account_id), "segment": get_segment_context(transaction.segment_id), "merchant": get_merchant_context(transaction.merchant_id), "metadata": transaction.custom_fields } # Step 2: Call Tracer try: response = http_post( url="https://tracer.example.com/v1/validations", headers={"X-API-Key": API_KEY}, json=payload, timeout_ms=100 ) except Timeout: return apply_fallback_policy() except ServerError: return retry_once_or_fallback() # Step 3: Handle decision if response.decision == "ALLOW": return proceed_with_transaction() elif response.decision == "DENY": return reject_transaction(response.reason) elif response.decision == "REVIEW": return queue_for_manual_review(response.validationId) ``` *** ## Next steps *** * **[Rules engine](./rule-engine.mdx)** - Create rules that evaluate against the context you provide * **[Spending limits](./spending-limits.mdx)** - Configure limits that apply to your transaction scopes * **[Audit and compliance](./audit-compliance.mdx)** - Query validation history and audit trail