Integration Security and Operations

Purpose

This document defines the operational and security expectations for Tov+ integrations.

Security rules

Least privilege

• every integration must receive the smallest scope that satisfies its purpose
• read-only should be the default unless mutation is clearly required
• partner category alone must never imply broad access

Credential security

• secrets must be generated with strong entropy
• stored values must be hashed or encrypted at rest
• credentials must be rotatable and revocable
• raw secrets must never appear in ordinary logs

Webhook security

• outbound webhooks must be signed
• inbound partner webhooks must verify signature or shared secret before processing
• receivers should validate timestamp freshness to reduce replay risk

Environment separation

• development, staging, and production credentials are separate
• production events must never be delivered to non-production endpoints
• environment should be visible in integration configuration and audit records

Tenant isolation

• integrations must not cross occasion boundaries without explicit grants
• platform-scoped service integrations still must not read arbitrary occasion data unless needed

Access review and expiration

• partner integrations should support expiration or review dates where appropriate
• dormant credentials should be revocable
• long-lived integrations should undergo periodic access review

Operational expectations

Auditability

Record at minimum:

• integration id
• credential id
• environment
• action/resource/scope
• request or delivery id
• outcome
• timestamp

Health and status

Each integration should expose operational state such as:

• healthy
• degraded
• failing
• revoked
• disabled

Retry and failure handling

Requirements:

• classify failures as retryable or terminal
• store delivery/sync attempt history durably
• support replay or manual retry tooling later
• surface repeated failure patterns via logs/metrics

Alerting expectations

Alert-worthy conditions include:

• repeated webhook delivery failures
• repeated authentication failures
• integration sync backlog growth
• persistent provider schema mismatch

Support and debugging

Support tooling should be able to inspect:

• recent requests/deliveries
• failure categories
• correlation ids
• scope configuration

Support tooling must not expose:

• raw active secrets
• unnecessary private customer data

Failure model

Recommended terminal states:

• active
• degraded
• retrying
• failed_terminal
• revoked
• disabled

Recommended response patterns:

• transient failures -> retry with backoff
• terminal failures -> stop and require operator review
• auth failures -> disable or quarantine quickly if repeated

Observability expectations

Use structured logs and metrics for:

• request counts by integration
• webhook delivery latency
• sync duration
• retry counts
• success/failure rates by adapter type

Correlation ids should connect:

• originating business event
• outbound job id
• delivery attempt
• inbound or outbound API request

Final summary

The integration operational model is built around least privilege, explicit credentials, signed webhook traffic, environment separation, durable auditability, and observable retry/failure handling. Integrations are treated as security-sensitive machine participants, not trusted shortcuts.