> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/operations-and-safety/compliance.md). # Compliance and Audit The Amigo platform is built for regulated healthcare environments. Its technical controls and evidence surfaces can support a customer's compliance program, but product behavior alone does not establish legal compliance. Applicable agreements, deployment configuration, operating procedures, and customer responsibilities remain part of the control environment. ## Authentication and Access Control The platform applies authentication, authorization, and workspace scoping at defined service and route boundaries. The exact controls depend on the surface and credential type, so customers should validate the routes they use rather than infer universal coverage from this overview. ### Role-Based Access Control Permissions follow five default workspace roles. Viewer is the read baseline. Member and operator branch from that baseline for different jobs; admin combines member capabilities with configuration administration and supported operator actions. Owner currently carries the admin permission set but is required by owner-only workflows. The API-key permission catalog is the authoritative source for the current defaults. | Role | Permissions | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Viewer** | Read the workspace resources and data included in the default viewer grant set. | | **Member** | Viewer access plus supported create, send, trigger, conversation, and data-write operations. Configuration update and delete operations remain admin-level. | | **Operator** | Viewer access plus review actions and supported live-run guidance or takeover operations. Operator is not a data-ingestion role. | | **Admin** | Member access plus configuration CRUD, member administration, audit access, supported operator actions, and workspace administration. The default catalog includes `Workspace:Delete`, although individual routes can add conditions. | | **Owner** | The admin permission set plus eligibility for owner-only workflows, including workspace archive and issuing owner-role API keys. | 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 API keys provide bearer-token authentication for programmatic access. A key selects one default role and can optionally carry a subset of that role's permissions. The requested role and permissions cannot exceed the creator's own access, and only an owner can issue an owner-role key. ### 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 Supported interactive sessions apply configured idle timeouts. If a session is inactive beyond the configured threshold, it is terminated automatically. Concurrent-session limits can expire the oldest session when a new login exceeds the configured limit. 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. Sender-constrained tokens remove the need for rotation entirely - see [Token Security](#token-security) below. ### IP Allowlists Workspaces can configure CIDR-based IP restrictions for supported identity token flows. When an active allowlist is resolved successfully, an address outside the configured ranges is rejected. If the policy cannot be evaluated, the request is allowed, so combine this control with network and credential safeguards rather than treating it as a universal request firewall. ### Progressive Account Lockout Supported identity flows record failed attempts and apply progressive lockout thresholds. If lockout state cannot be evaluated, the request is treated as unlocked. Rate limits and upstream identity-provider controls remain separate safeguards. ### Agent Session Tokens Supported agent sessions use short-lived delegated tokens bound to a workspace and a call or job. Administrative, credential-management, and further-delegation scopes are stripped, and the effective role is capped below the admin tier. Tool availability and reads still depend on the runtime policy and any external-principal binding; the token alone should not be interpreted as entity-scoping every read. Supported agent world-write tools use an additional server-constructed entity write scope. ### External Caller Identity A customer-hosted application can bind its verified external user identity to a patient entity in the workspace. At conversation start, the platform resolves that binding so a recognized caller receives the correct world-model context and returning-user memory. An unbound caller starts anonymously rather than being matched by guesswork. Patient identity bindings are separate from [external principals](#external-principals), which represent clinicians and other role-scoped users. A patient binding cannot target an entity with active principal roles, preventing patient recognition from becoming an authorization path. This binding surface is not part of the current public Platform API contract. ### 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 an industry-standard key derivation function, following OWASP recommendations, before storage. 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 standard (RFC 9449, Demonstration of Proof-of-Possession). When enabled, access and refresh 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, and eliminating the grace window where two valid tokens coexist. ## Identity Linking and Provider Trust When an operator accepts an invitation through one authentication method (such as a magic link or email code) and later signs in through a different provider (such as Google), the platform can automatically link the two identities to the same operator entity. This cross-provider linking is gated by a trust rule: the second provider must be authoritative for the operator's email mailbox at the time of sign-in. For corporate domains, this means the provider must manage the domain's accounts through its own administration. For consumer email addresses hosted natively by the provider, controlling the account is equivalent to controlling the inbox. A consumer account registered under a third-party corporate email address does not qualify, because the provider's historical email verification does not prove current inbox control. If an operator entity already has a linked identity for the incoming provider under a different subject, the platform refuses the new link and logs an identity conflict for administrator resolution. Every automated identity link is audit-logged with the providers involved, email address, and external subject identifier. ## Federated Identity and Invitation Recovery Workspace operators are sometimes invited via one authentication method (such as magic link or email one-time password) and later expected to sign in through the workspace's federated identity provider (OIDC or SAML). Because the invitation was accepted under a different provider, the operator's identity record does not match the federation source, and the federated login would otherwise fail. The platform handles this by checking whether the email asserted by the identity provider matches an active member of the federation source's own workspace. If it does, the login succeeds with the token scoped strictly to that workspace - a workspace-scoped identity provider can never issue tokens for workspaces outside its own boundary. No durable federation identity is created during this recovery, so each subsequent login re-verifies active workspace membership. Pending invitations are not auto-accepted from an identity provider assertion - operators accept invitations through the standard console flow, which independently verifies the invited email. This recovery path is audit-logged with a dedicated event that records the federation source, the matched provider, and the asserted email. ## Operator Identity Enforcement Supported operator action routes, including join, mode switch, leave, guidance, wrap-up, access-token, and run-scoped takeover routes, enforce server-side identity binding. The platform verifies that the authenticated caller matches the operator profile being acted as before allowing the action to proceed. Mismatched identity attempts are logged and rejected. This prevents a client-supplied operator identifier from becoming an impersonation path on those routes. ## Audit The platform provides a workspace-scoped audit surface for supported platform events, including sensitive data access and selected configuration or operator actions. Available fields depend on the event producer; the audit schema supports actor identity, timestamp, credential, network context, action, resource, and PHI classification. On the MCP data access surface, covered reads that return patient-identifying data - including entity listings that project display names and medical record numbers - schedule an audit record with the action, resource type, tool name, and result status. Audit-write failures surface operational warnings but do not make the read fail, so customers should monitor audit delivery rather than infer transactional coupling. Schema-discovery operations that return only tool metadata and no PHI are excluded. Audit API responses conform to the published response schema. Fields that are not available for a particular producer are returned as nullable values rather than inferred. 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. ### PHI Access Logging Supported PHI-sensitive routes classify their audit events for compliance reporting, including selected entity reads, patient-data access, call recordings, and intelligence views. Customers should validate route coverage against their own audit requirements rather than infer universal coverage from the PHI report alone. ### Principal Session Audit When a workspace credential starts a conversation anchored to an entity that has an active external role assignment, the platform treats this as principal impersonation - the session acts as that external principal with the principal's role-scoped tool access. This action requires admin or owner credentials and is recorded as a dedicated audit event (`principal.session.opened`) capturing the conversation ID, the acting credential, and the target entity. This ensures that every principal impersonation through the API-start path is traceable to a specific credential and entity. ### 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. ### Workspace Access Auditing Supported Identity workspace-access routes are wired to append structured audit events for member additions and reactivations, role changes, ownership transfers, removals, invitation sends and resends, acceptance, decline, revocation, and membership bootstrap or auto-provisioning. Successful audit records include the acting identity, workspace, target resource, and operation-specific details. Membership mutation and audit append are separate operations, so monitor audit delivery and reconcile access state rather than treating the log as transactionally complete proof of every transition. These records can support SOC 2 access reviews and HIPAA workforce-clearance evidence. ### Audit Queries The compliance dashboard provides four views into the audit trail: | View | What It Shows | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Audit events** | Retained audit entries with filters for service, action, actor, resource type, resource ID, PHI classification, and date range | | **PHI access report** | Covered entries classified as PHI access, for use in customer investigation and reporting workflows | | **Entity access log** | Retained audit entries that match a specific resource identifier | | **Audit summary** | Counts of matching events, PHI-classified entries, actors, and services within the requested scope | ### 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 made available through 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 evidence exports are available: | Report | What It Provides | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **HIPAA evidence report** | Produces a partial evidence summary for a configurable period (default 90 days), including audit statistics, configured retention values, declared encryption flags, and an API-key summary. The current response returns `compliance_status: partial`; MFA coverage, SSO enforcement, allowlist status, session timeout, and locked-account fields are not currently populated. | | **Access review export** | Lists API key credentials with role, status, and activity dates. Interactive user and session credentials are not included in the current export. | ### Audit Trails Through Event Sourcing The [world model](/data/world-model.md) stores observations as append-only events. When a modeled fact changes, a new event can supersede the prior observation without rewriting it. This event history is distinct from configuration records, audit events, and external destination logs, which follow their own storage models. This architecture provides event-level evidence for modeled data: * **What was known, and when.** For modeled facts with retained event history, replay up to a timestamp can reconstruct the observations available at that point. * **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 supported resources.** API access is scoped to authenticated accounts, and covered access paths emit separate audit events. Event history and access audit serve different purposes. Event history explains changes to modeled state; the audit surface records covered actions by authenticated actors. Neither should be treated as a substitute for destination-system evidence. ## HIPAA Considerations Amigo handles protected health information (PHI) in the normal course of healthcare operations. The platform's architecture addresses key HIPAA requirements: ### Isolation Customer-facing PHI access is scoped to the workspace at defined storage, query, and route boundaries. Each workspace has its own logical world model, data-source configuration, and access controls. A multi-site healthcare organization can use separate workspaces per clinic so each site's patient data is available only through credentials authorized for that workspace. Customers should still validate the exact storage and access paths in their deployment rather than infer a universal isolation mechanism from this overview. ### Access Control The platform provides RBAC and supports MFA, SSO, IP restrictions, session controls, and progressive lockout on their documented identity and application paths. These controls do not all apply at every access point, and allowlist or lockout backing-service failures can fail open. See [Authentication and Access Control](#authentication-and-access-control) for the boundaries of each control. #### External Principals For sessions driven by external users (such as partner clinicians or care coordinators), the platform supports entity-anchored, role-scoped access control. An external user is bound to a workspace entity with assigned roles, and role grants determine which integration endpoints, skills, and knowledge base scopes the session can access. Grant changes insert a new record and supersede the prior one, preserving authorization history. Identity injection through token-exchange bindings prevents the agent from supplying or overriding a bound identity parameter. Sessions without an external-principal binding use the ordinary workspace and session authorization path; they do not inherit a principal role grant. ### Data Minimization The three data channels in the world model (ambient, queried, extracted) control what information is available to the agent at a given moment. Ambient context is configured per service, queried data requires an explicit tool call, and extracted observations retain source and confidence. External delivery is a separate policy decision; configured private-preview proposal flows add human approval only for the specific writes they gate. #### 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. ### 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 through the API. They are decrypted only for authorized runtime use. This reduces exposure from direct database reads and backups; it is not a claim that field encryption alone defeats every database or key-management compromise. ## Confidence and External Write Authorization ```mermaid flowchart LR V[Patient interaction] --> E[Observation with provenance] E --> W[World model confidence and conflict resolution] W --> G{Outbound policy selects this event?} G -->|Private-preview review policy| P[External write proposal] P -->|Approved| X[External system] P -->|Rejected| R[No delivery] G -->|No approval required| X ``` [Confidence and provenance](/data/world-model.md) preserve where a modeled value came from and help prevent a less reliable observation from silently replacing stronger evidence. External-write approval is a separate private-preview authorization path for configured mutations; it is not a universal review stage. Consider the flow: 1. A patient mentions a new pharmacy address during a phone call. 2. The agent records the observation with transcript provenance and source-appropriate confidence. 3. Higher-confidence evidence can supersede the value without erasing the original observation. 4. Outbound policy determines whether the event is eligible for unattended delivery or requires a configured proposal flow. 5. Where private-preview review is enabled, an approved proposal enters its separate delivery path, with destination-specific retry and failure semantics. Recording an observation therefore does not confirm an external mutation. Event provenance, proposal decisions where enabled, connector outcomes, and destination records provide evidence at separate boundaries. Customers that need an end-to-end chain should correlate those records with stable identifiers and verify the destination state. ## 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 a SOC 2 Type II report and supports HIPAA-regulated workloads. BAAs are available for covered customers. Current assurance materials are available through the Trust Center. {% endhint %} | Assurance | Status | Scope | | ----------------- | ------------------------ | ---------------------------------------------------------------------------- | | **SOC 2 Type II** | Current report available | Security trust services criteria within the report's stated scope and period | | **HIPAA** | Supported with BAA | PHI safeguards and contractual coverage defined by the applicable agreement | | **GDPR** | DPA available | EU data-processing terms defined by the applicable agreement | Downstream vendor coverage, subprocessor terms, and any applicable BAAs are controlled assurance materials rather than guarantees inferred from this product overview. BAAs are available for HIPAA-covered customers. Contact or visit the [Trust Center](https://trust.amigo.ai) for certification details and audit reports. ## Webhook Security Classic SMS, email, and iMessage use cases can POST inbound-turn payloads to their configured receiver. Classic channel delivery signs those payloads with HMAC-SHA256 using a per-use-case secret. Explicit secret rotation returns the new secret once and dual-signs with the old and new versions for a 30-minute grace window. Changing the webhook URL remints the secret without that grace period. This Classic channel webhook path is separate from Platform triggers. Platform triggers use authenticated trigger-fire calls rather than Platform-hosted vendor webhook destinations. Customers verify a vendor webhook in their own integration layer, normalize its input, and then call the trigger endpoint with a permitted Platform credential. Classic webhook signing and secret-rotation behavior does not describe this Platform trigger path. ## Infrastructure Security * **Encryption** - The Platform compliance response declares encryption at rest and in transit. Detailed scope, protocols, and control evidence belong in the current assurance package. * **Identity controls** - SSO, MFA, session controls, IP restrictions, and progressive lockout apply on their documented paths and have the availability boundaries described above. * **Environment boundaries** - Workspace region and environment are explicit routing and data-residency properties. Do not infer a broader network-isolation guarantee from those fields alone. * **Operational assurance** - Current vulnerability-management practices, incident commitments, penetration-test coverage, transport controls, and change-review evidence are available through the Trust Center or applicable contract. This page does not promise a universal mTLS design or fixed operational cadence. ## Data Lineage Boundaries World-model events carry event-level source, confidence, and supersession information. The current per-entity provenance view exposes entity identity and historical merge information, but it should not be treated as a complete chain of custody. In particular, the unified lineage response does not currently populate outbound-sink or review-history records. Use connector delivery outcomes and destination-system records to prove an external mutation. Use the audit API for covered actor actions and PHI access. Use external write proposal records only where that private-preview flow is enabled. These records can be correlated, but they are not presented as one universally complete per-entity timeline. ## Retention Policies Per-workspace retention policies record intended retention periods. The default shown by the platform is 2,190 days; organizations should confirm that value against their record type, contracts, jurisdictions, and legal-hold requirements. | 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** records an override to the configured retention policy and includes a reason for documentation. Because automated retention deletion is not yet enforced, organizations must implement and verify the corresponding operational hold process. {% 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 %} ## Ongoing Compliance Compliance is not a one-time certification. The platform supports ongoing compliance through: * **Audit queries** - Covered platform events can be filtered by actor, service, action, resource, PHI classification, and date * **PHI access logging** - Covered PHI-sensitive paths classify audit events for dedicated reporting and investigation * **Event provenance** - World-model observations retain source, confidence, and supersession evidence * **Retention policies** - Documented defaults with per-workspace configurability and legal hold; automated deletion is not currently enforced * **Compliance reports** - A partial HIPAA evidence summary and an API-key access-review export * **External write decisions** - Private-preview proposal records preserve reviewer decisions for the specific mutations routed through that flow * **Authored safety policy** - Context graphs, tool permissions, escalation instructions, and operator procedures define the active runtime boundary (see [Runtime Safety](/operations-and-safety/runtime-safety.md)) * **Assurance evidence** - Current control evidence and operating commitments are maintained in the Trust Center and applicable agreements Event history, confidence-aware outbound policy, covered audit events, access controls, and documented operating procedures provide evidence for compliance programs. Organizations remain responsible for validating coverage against their legal, contractual, and governance requirements. For API details on workspace permissions, audit reporting, runtime controls, and operator workflows, see the [Developer Guide](https://docs.amigo.ai/developer-guide/platform-api/safety). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/operations-and-safety/compliance.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.