# Compliance and Audit

The Amigo platform is built for regulated healthcare environments. Compliance follows from architectural decisions made for operational reasons. The same choices that make the system reliable also satisfy regulatory requirements.

## Authentication and Access Control

The platform enforces authentication and authorization at every layer. Access control is built into how every request is processed, how every API call is validated, and how every piece of patient data is scoped.

### Role-Based Access Control

Permissions follow four cumulative tiers. Each tier includes everything the one below it can do.

| Role       | Permissions                                                                               |
| ---------- | ----------------------------------------------------------------------------------------- |
| **Viewer** | Read-only access to workspace data and conversations.                                     |
| **Member** | Create and modify agent configurations, context graphs, and data sources.                 |
| **Admin**  | Manage team access, API keys, and workspace settings.                                     |
| **Owner**  | Full control including workspace deletion, ownership transfer, and compliance operations. |

Permissions are workspace-scoped. A user can be an admin in one workspace and a viewer in another. This matters for multi-site healthcare organizations where clinical staff at one location should not have configuration access to another.

### API Keys

Bearer token authentication for programmatic access. Keys are workspace-scoped with configurable permissions - you can issue a key with viewer-level access for a reporting integration, or an admin-level key for infrastructure automation. Keys cannot exceed the permissions of the account that created them.

### SSO with Identity Federation

Users authenticate through their organization's identity provider. The platform supports both OIDC and SAML federation. Auto-provisioning creates platform credentials on first login based on domain policies, so IT teams do not need to manually create accounts for every user.

### Multi-Factor Authentication

TOTP-based second factor for accounts that do not use SSO. Recovery codes are generated at enrollment for account recovery if a device is lost. MFA is enforceable per SSO connection with admin visibility into enrollment coverage across the workspace.

### Session Enforcement

Interactive sessions follow HIPAA-compliant idle timeouts. If a session is inactive beyond the configured threshold, it is terminated automatically. Concurrent session limits prevent credential sharing - new logins beyond the limit force the oldest session to expire.

Token rotation includes theft detection. When a refresh token is used, a new one is issued and the old one is invalidated. If the old token is presented again (indicating it was copied before rotation), all sessions in that token family are revoked immediately.

The platform also supports sender-constrained tokens (RFC 9449). When enabled, refresh tokens are cryptographically bound to the client that created them - the client proves key possession on each refresh, making a stolen token useless without the corresponding private key. Because the token is bound to a key pair, rotation is unnecessary and there is no grace window where two valid tokens coexist.

### IP Allowlists

Workspaces can restrict API access to specific IP ranges using CIDR-based rules. Requests from outside the allowlist are rejected before they reach any business logic. Useful for locking down production integrations to known infrastructure.

### Progressive Account Lockout

Failed authentication attempts trigger escalating lockouts with increasing cooldown periods to prevent brute force attacks.

### Agent Session Tokens

When the platform handles a patient interaction, it creates a short-lived session token scoped to the minimum permissions needed for that conversation. The agent can read patient data relevant to the interaction and write events, but it cannot modify workspace configuration, manage users, or access data outside the current interaction's scope. If something goes wrong during a conversation, the blast radius is limited to what that session token can reach. The agent never holds workspace-level credentials.

### Machine-to-Machine Authentication

The platform supports OAuth 2.0 client credentials grants for machine-to-machine integrations. Services authenticate by exchanging a client ID and secret for an access token, without user interaction. This is the standard pattern for backend integrations, scheduled jobs, and CI/CD pipelines that need to call the platform API programmatically.

## Credential Security

Client secrets used for machine-to-machine authentication are hashed with a key derivation function (PBKDF2-SHA256 with 210,000 iterations) before storage, following OWASP recommendations. Plaintext secrets are returned once at creation time and are never stored or retrievable afterward.

## Token Security

The platform supports sender-constrained tokens using the DPoP (Demonstration of Proof-of-Possession) standard. When enabled, access tokens are cryptographically bound to a key held by the client application. Even if a token is intercepted in transit or extracted from logs, it cannot be used by a different client because the receiving service verifies that the caller holds the corresponding private key.

Sender-constrained tokens also eliminate a class of race conditions in token refresh flows. Because the token is bound to a specific client key, the platform does not need to rotate refresh tokens on each use - removing the window where concurrent refresh attempts from multiple tabs or network retries could invalidate a session.

## Audit

### Session Token Delegation

When a short-lived session token is minted from a parent credential, the platform records a structured audit trail of the role derivation decision. This includes the parent's claimed role, the role inferred from the parent's actual permissions, the effective role assigned to the child token, whether the role was capped due to privilege restrictions, and the parent token's provenance chain. If a parent's role claim is rejected as inconsistent with its permissions, a dedicated audit event is emitted so security teams can identify forged or drifted credentials without searching through general session logs.

Audit log entries are scoped to individual workspaces. Each entry records the action, the user or service that performed it, and the workspace where it occurred. Queries return only entries belonging to the requesting workspace, so multi-tenant deployments maintain strict isolation between workspaces. Operations that affect multiple workspaces - such as auto-provisioning a user into several workspaces at once - produce a separate audit entry per workspace rather than a single cross-workspace record. Trails Through Event Sourcing

The [world model](/data/world-model.md) is event-sourced. Every piece of data that enters the system is written as an immutable, append-only event. Events are never modified or deleted. When information changes, a new event supersedes the old one, but the old event remains in the log permanently.

This architecture produces a complete audit trail by default:

* **What was known, and when.** You can reconstruct the state of any entity at any point in time by replaying events up to that timestamp.
* **Where data came from.** Every event records its source (EHR sync, voice call, manual import, agent inference) and its confidence level.
* **What changed, and why.** When an entity's state changes, the event that caused the change is traceable. Superseded events are linked to the events that replaced them.
* **Who accessed what.** API access is scoped to authenticated accounts with role-based permissions, and access logs are maintained.

This is not a logging system added to a mutable database. The event store *is* the database. The audit trail is not a secondary artifact; it is the primary data structure.

## HIPAA Considerations

Amigo handles protected health information (PHI) in the normal course of healthcare operations. The platform's architecture addresses key HIPAA requirements:

### Isolation

PHI is isolated at the workspace level. Each workspace has its own world model, its own data sources, and its own access controls. Data does not cross workspace boundaries. A multi-site healthcare organization can run separate workspaces per clinic, ensuring that each site's patient data is accessible only to accounts with permissions in that workspace. Workspace boundaries are enforced at the query level - even internal joins (such as enriching call lists with intelligence data) include workspace-scoped filters to prevent cross-workspace data exposure.

### Access Control

The platform enforces RBAC, MFA, SSO, IP allowlists, session enforcement, and progressive lockout at every access point. See [Authentication and Access Control](#authentication-and-access-control) above for the full breakdown.

### Data Minimization

### Call Analysis Pipeline

The post-call analysis pipeline follows strict data minimization principles. When structured execution traces are forwarded for quality analysis, only structural and categorical signals are included - tool names, input key names, output lengths, success/failure flags, state names, confidence scores, emotion labels, and latency values. Raw tool inputs and outputs are excluded entirely because they may contain patient information. Rather than attempting incomplete redaction of sensitive data, the platform eliminates the surface area by forwarding only the structural shape of each interaction.

The three data channels in the world model (ambient, queried, extracted) control what information is available to the agent at any given moment. The agent receives the minimum context needed for the current conversation, not a full dump of the patient's record. Ambient context is configured per service; queried data requires an explicit tool call; extracted data flows through review before reaching the EHR.

### Encryption

Data is encrypted in transit and at rest. Voice call audio, transcripts, and world model events are stored with encryption. Specific encryption standards and certifications are available on request.

### Field-Level Encryption

Sensitive user data is encrypted at the field level in the database. User variables that contain credentials or API keys for tool execution are encrypted at rest and are write-only - once set, they can never be read back through the API. They are decrypted only inside the tool's isolated execution environment at runtime. This prevents credential exposure even if the database is compromised.

## Confidence Gates as a Compliance Mechanism

```mermaid
flowchart LR
    V[Voice Call] -->|0.3-0.5| E[Event Written]
    E --> AR{Automated\nReview}
    AR -->|Verified| P[Promoted to 0.7]
    AR -->|Uncertain| HQ[Human Review Queue]
    HQ -->|Approved| PA[Promoted to 0.95]
    HQ -->|Rejected| X[Excluded]
    P --> EHR[EHR Sync]
    PA --> EHR
```

The [three-layer confidence gates](/data/connectors-and-ehr.md) in the connector runner are a safety mechanism, but they also serve a compliance function. They ensure that unverified data does not reach systems of record.

Consider the flow:

1. A patient mentions a new pharmacy address during a phone call
2. The agent writes this as an event with voice confidence (0.5)
3. The automated review judge evaluates whether the extracted address matches what was actually said in the transcript
4. If verified, confidence is upgraded. If uncertain, the event is flagged for human review.
5. Only events that pass all three gates (source confidence, automated review, and human review where required) are synced back to the EHR

This means that a misheard word, a misinterpreted statement, or an incorrect inference by the agent does not automatically become part of the clinical record. The gates catch errors before they propagate.

For regulated environments, this is significant. It provides a documented, traceable verification process between "something was said on a phone call" and "a record was updated in the EHR." Auditors can examine the event chain: the original transcript, the extracted data, the review judgment, and the final write.

## PHI in Voice Calls

Voice calls present specific PHI handling considerations:

* **Transcripts** contain PHI by nature (patient names, conditions, medication details). They are stored in the workspace's world model with the same isolation and access controls as all other data.
* **Audio recordings** are stored encrypted and scoped to the workspace. Retention policies are configurable.
* **Emotion detection data** is processed in real time and stored as aggregate signals (valence, arousal, trend), not raw audio. The emotion pipeline does not retain audio segments after processing.

## Certifications and Agreements

{% hint style="success" %}
Amigo maintains active SOC 2 Type II and HIPAA certifications with continuous third-party monitoring. BAAs are available for HIPAA-covered customers.
{% endhint %}

| Certification     | Status    | Scope                                                                           |
| ----------------- | --------- | ------------------------------------------------------------------------------- |
| **SOC 2 Type II** | Active    | Security trust services criteria, continuous monitoring via third-party auditor |
| **HIPAA**         | Active    | PHI protection across all platform services                                     |
| **GDPR**          | Compliant | EU data processing, DPA available                                               |

**Business Associate Agreements (BAAs)** are executed with all vendors that handle PHI, spanning cloud infrastructure, AI/LLM providers, voice processing, data storage, and monitoring services.

BAAs are available for HIPAA-covered customers. Contact <compliance@amigo.ai> or visit the [Trust Center](https://trust.amigo.ai) for certification details and audit reports.

## Webhook Security

Webhook deliveries are signed with HMAC-SHA256 using a per-organization secret. During secret rotation, the system sends signatures from both the old and new secrets in the delivery headers for a 30-minute transition window. This ensures that webhook consumers can verify signatures without interruption during rotation. Delivery attempts are tracked with full audit trails (timestamps, HTTP status codes) and retained for 30 days.

For inbound webhooks (external systems posting to the platform to fire triggers), the same HMAC-SHA256 verification applies with secret rotation support. Event type filtering decisions are based exclusively on the signed request body - unsigned headers are not used for dispatch decisions, preventing event type spoofing through replay attacks with modified headers.

## Infrastructure Security

<details>

<summary>Full infrastructure security details</summary>

* **Encryption at rest** - All data encrypted at rest, including database storage, data platform storage, and file storage
* **Encryption in transit** - TLS 1.2+ on all connections, mutual TLS between services
* **Access control** - SSO with identity provider, MFA enforced, minimum-length password policy, progressive account lockout, HIPAA-compliant idle session timeouts, concurrent session limits per entity
* **Network isolation** - Separate environments for staging and production with no cross-environment access
* **Vulnerability management** - Continuous automated scanning with weekly triage of findings
* **Incident response** - P1 critical incidents: 24-hour response SLA; breach notification within 48 hours to customers, 72 hours to regulators
* **Penetration testing** - Semi-annual schedule (Q2 and Q4)
* **Code review** - Mandatory peer approval on all changes with automated quality checks

</details>

## Unified Audit Trail

The platform maintains a unified audit trail across all services. Every significant action - API calls, data access, configuration changes - is recorded with actor identity, timestamp, IP address, credential used, and resource affected.

### PHI Access Logging

Access to PHI-sensitive endpoints is automatically detected and logged. The platform recognizes 12 route patterns as PHI-sensitive, including entity reads, patient data access, call recordings, and intelligence profiles. PHI access events are tagged for compliance reporting.

### Audit Query API

Four endpoints power the compliance dashboard:

| Capability            | What It Shows                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Audit events**      | Full audit log with filters for service, action, actor, resource type, resource ID, PHI-only, and date range |
| **PHI access report** | Who accessed what patient data, when, and from where - required for HIPAA breach investigation (164.312(b))  |
| **Entity access log** | All audit events for a specific resource (patient, call, etc.)                                               |
| **Audit summary**     | Total events, PHI access events, unique actors, and services with activity                                   |

Audit events are non-blocking - they are buffered and written asynchronously so they do not add latency to the request path.

### Workspace Access Auditing

Workspace membership and invitation operations are audited end-to-end. Every member addition, role change, removal, invitation send, acceptance, decline, and revocation produces a structured audit event with actor identity and target details. This covers the full access lifecycle - from initial invitation through role changes to eventual removal - providing the evidence trail needed for SOC 2 user access reviews and HIPAA workforce clearance procedures.

## Data Lineage

Each entity in the world model has a full data lineage that traces where its data came from, how it was verified, and where it was synced. The lineage composes three layers:

* **Provenance** - Contributing data sources, confidence history over time, and entity resolution merge events
* **Outbound sync sinks** - Which external systems received this entity's data, sync status, and timestamps
* **Review history** - Review queue items for the entity, including verdicts and reviewer actions

This lineage is available per-entity and is designed for compliance audits where you need to demonstrate the full chain of custody for a piece of data.

## Retention Policies

Per-workspace retention policies define how long different data types are kept. All defaults are HIPAA-compliant (6 years / 2190 days):

| Data Type          | Default Retention   | Configurable Range |
| ------------------ | ------------------- | ------------------ |
| Call recordings    | 2190 days (6 years) | 1-100 years        |
| Call transcripts   | 2190 days           | 1-100 years        |
| Audit logs         | 2190 days           | 1-100 years        |
| World model events | 2190 days           | 1-100 years        |
| PHI data           | 2190 days           | 1-100 years        |

**Legal hold** overrides all retention - when enabled, no data is deleted regardless of policy. Legal holds include a reason field for documentation.

{% hint style="info" %}
Retention policies are currently advisory - the policy is stored, displayed, and available for compliance reporting, but automated deletion is not yet enforced.
{% endhint %}

## Audit Log Export

Audit logs can be exported as NDJSON files for offline analysis, long-term archival, or handoff to auditors. Exports are generated on demand for a specified date range and uploaded to secure cloud storage with time-limited download URLs (12 hours).

Exports are capped at 50,000 events per request. The export itself is recorded as an audit event (with PHI flag if the export contains PHI access data).

## Compliance Reporting

Two compliance reports are available for auditors:

| Report                    | What It Provides                                                                                                                                                            |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HIPAA evidence report** | Aggregates audit statistics, retention policy, encryption status, and API key summary for a configurable period (default 90 days). Produces a compliance status assessment. |
| **Access review export**  | Lists all API key credentials with role, status, and activity dates for SOC 2 attestation.                                                                                  |

## Ongoing Compliance

Compliance is not a one-time certification. The platform supports ongoing compliance through:

* **Unified audit trail** - Every significant action across all services produces a traceable audit event with actor identity and resource context
* **PHI access logging** - Automatic detection and logging of access to patient health information, with dedicated reporting for breach investigation
* **Data lineage** - Per-entity provenance, sync history, and review chain of custody
* **Retention policies** - HIPAA-compliant defaults with per-workspace configurability and legal hold
* **Compliance reports** - HIPAA evidence and SOC 2 access review exports
* **Review queues** - Flagged interactions are surfaced for human review on an ongoing basis
* **Monitor concepts** - Semantic rules can be configured to detect compliance-relevant patterns in real time (see [Runtime Safety](/safety-and-compliance/runtime-safety.md))
* **Regulation templates** - Pre-built rule sets for healthcare compliance requirements can be applied and customized per workspace
* **Quarterly evidence collection** - User access reviews, vendor security assessments, risk assessment updates, control self-assessments

Immutable event sourcing, confidence-gated writes, unified audit trails, data lineage, and real-time monitoring together provide the infrastructure needed to demonstrate compliance to auditors, regulators, and internal governance teams.

For API details on workspace permissions, safety monitors, and regulation templates, see the [Developer Guide](https://docs.amigo.ai/developer-guide/platform-api/platform-api).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/safety-and-compliance/compliance.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.