# AI Policy Editor
Source: https://www.trycomp.ai/docs/ai-policy-editor

Use AI to edit and improve organizational policies for SOC 2, ISO 27001, and GDPR compliance

### About AI Policy Editor

The AI Policy Editor is an intelligent assistant that helps you create, edit, and improve organizational policies. Built with deep knowledge of compliance frameworks like SOC 2, ISO 27001, and GDPR, the assistant understands governance, risk, and compliance (GRC) requirements and can help ensure your policies meet industry standards.

**Key Benefits:**

* **Natural Language Editing**: Describe changes in plain English and let AI handle the formatting
* **Compliance Expertise**: Get suggestions aligned with SOC 2, ISO 27001, GDPR, and other frameworks
* **Visual Diff Review**: See exactly what changed before applying any edits
* **Non-Destructive Workflow**: Review and approve all changes before they're saved

### Getting Started

#### Step 1: Open the Policy Editor

1. Navigate to **Policies** in your organization dashboard
2. Click on any policy to open it
3. Select the **Editor View** tab

#### Step 2: Enable the AI Assistant

1. Click the **AI Assistant** button in the top-right corner of the editor
2. A chat panel will appear on the right side of the screen
3. You're now ready to start editing with AI

![AI Policy Editor Assistant Panel](https://mintcdn.com/bubbaaiinc/TiyPHBubFjmEvmyZ/images/ai-policy-editor-assistant.png?fit=max\&auto=format\&n=TiyPHBubFjmEvmyZ\&q=85\&s=d39927f904937de68ce2a2816b7885e3)

### Using the AI Assistant

The AI assistant responds to natural language requests. Simply describe what you want to change, and the assistant will propose a complete updated version of your policy.

**Example Prompts:**

| Request Type | Example Prompt |
| - | - |
| Add content | "Add a data retention section that specifies 7-year retention for financial records" |
| Improve compliance | "Make this policy more SOC 2 compliant" |
| Simplify language | "Simplify the language to be more readable" |
| Add specifics | "Add specific roles and responsibilities for incident response" |
| Framework alignment | "Update this to align with ISO 27001 Annex A controls" |

> [!NOTE]
>
> The AI always proposes complete policy content, not just fragments. This ensures formatting
> consistency and prevents accidental content loss.

### Reviewing Proposed Changes

When the AI proposes changes, you'll see a status indicator showing the progress:

* **Drafting**: The AI is preparing the updated policy
* **Running**: The proposal is being processed
* **Completed**: Changes are ready for your review

Once completed, a diff viewer appears below the editor showing:

* **Red lines**: Content being removed
* **Green lines**: Content being added

![AI Policy Editor Diff Viewer](https://mintcdn.com/bubbaaiinc/TiyPHBubFjmEvmyZ/images/ai-policy-editor-diff-viewer.png?fit=max\&auto=format\&n=TiyPHBubFjmEvmyZ\&q=85\&s=129f1ca52372ffb5d272cb6e8420fa6b)

#### Applying or Dismissing Changes

After reviewing the diff:

1. Click **Apply Changes** to accept the proposed edits
2. Click **Dismiss** to reject the changes and keep your current content

> [!TIP]
>
> Click "View proposed changes" in the chat to quickly scroll to the diff viewer.

### Best Practices

1. **Be Specific**: The more detail you provide in your request, the better the results. Instead of "improve this policy," try "add a section about password complexity requirements with 12-character minimum."

2. **Review Before Applying**: Always review the diff carefully before applying changes. The AI provides complete rewrites, so verify all sections are preserved as expected.

3. **Iterative Editing**: Make changes incrementally. Request one type of change at a time for easier review and better control over the final result.

4. **Ask Questions First**: If you're unsure what changes to make, ask the AI for suggestions. It can explain compliance requirements and recommend improvements before you commit to changes.

5. **Keep Policies Published**: Ensure your policies are published so other AI features (like Security Questionnaire) can reference the most current versions.

### Troubleshooting

**AI Assistant Not Appearing**

Ensure you're viewing the policy in **Editor View** mode, not PDF View. The AI assistant is only available in the editor.

**Changes Not Applying**

If changes fail to apply, check your network connection, ensure you have edit permissions for the policy, and try refreshing the page.

**Unexpected Content Changes**

If the AI modified sections you didn't intend to change, click **Dismiss** to reject the changes. Be more specific in your next request about which sections to modify, or reference sections by name.

### Support

For additional assistance with the AI Policy Editor:

1. Contact support at [support@trycomp.ai](mailto:support@trycomp.ai)
2. Join our [Discord community](https://discord.gg/compai) for peer support


# Create an information asset | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/assets/create-an-information-asset

/openapi.json post /v1/assets
Adds an asset to the ePHI inventory with its lifecycle flags (created, received, maintained, transmitted), owner and linked risks. Reusing a sourceKey.



# Delete an information asset | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/assets/delete-an-information-asset

/openapi.json delete /v1/assets/{id}
Removes an asset from the ePHI inventory. Linked risks stay in the register; only the link is removed. Prefer retiring (status) when the asset still existed.



# Get an information asset | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/assets/get-an-information-asset

/openapi.json get /v1/assets/{id}
Returns one information asset with its ePHI lifecycle flags, owner, source vendor or integration, and the risks linked to it.



# List information assets | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/assets/list-information-assets

/openapi.json get /v1/assets
Lists the organization's information assets (vendors, cloud resources, systems, devices, data flows) with their ePHI lifecycle flags, owner and linked.



# Update an information asset | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/assets/update-an-information-asset

/openapi.json patch /v1/assets/{id}
Updates an asset in the ePHI inventory. riskIds replaces the full set of linked risks; omit it to leave links unchanged.



# Get shared attachment download URL | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/attachments/get-shared-attachment-download-url

/openapi.json get /v1/attachments/{attachmentId}/download
Generate a signed download URL for a shared attachment linked to comments, evidence records, or compliance workflow reviews.



# Preview an attachment inline | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/attachments/preview-an-attachment-inline

/openapi.json get /v1/attachments/{attachmentId}/preview
Returns an attachment in a form the browser can display: an inline signed URL for PDFs, images and text files, or HTML converted from Word and Excel. Use it.



# Upload an attachment to any supported entity | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/attachments/upload-an-attachment-to-any-supported-entity

/openapi.json post /v1/attachments
Upload a base64-encoded file and attach it to a task, vendor, risk, comment, or other supported entity type. The file is uploaded to S3 and a database.



# List audit logs | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/audit-logs/list-audit-logs

/openapi.json get /v1/audit-logs
List organization audit logs for compliance activity, access changes, evidence updates, and customer-facing review events.



# Detect available cloud services for a | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/detect-available-cloud-services-for-a-connection

/openapi.json post /v1/cloud-security/detect-services/{connectionId}
Detect available cloud services for a connection in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings.



# Detect the GCP organization for a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/detect-the-gcp-organization-for-a-connection

/openapi.json post /v1/cloud-security/detect-gcp-org/{connectionId}
Detect the GCP organization for a connection in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings, and connect.



# Get a cloud security scan run by ID | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/get-a-cloud-security-scan-run-by-id

/openapi.json get /v1/cloud-security/runs/{runId}
Get a cloud security scan run by ID in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings, and connect cloud.



# List cloud security findings | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/list-cloud-security-findings

/openapi.json get /v1/cloud-security/findings
List cloud security findings discovered by scans so teams can prioritize remediation before issues become audit findings.



# List recent cloud security activity | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/list-recent-cloud-security-activity

/openapi.json get /v1/cloud-security/activity
List recent cloud security activity in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings, and connect cloud.



# List resolution, exception, and regression | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/list-resolution-exception-and-regression-history-for-a-connection

/openapi.json get /v1/cloud-security/history
List resolution, exception, and regression history for a connection in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services.



# List supported cloud providers | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/list-supported-cloud-providers

/openapi.json get /v1/cloud-security/providers
List supported cloud providers in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings, and connect cloud posture.



# Mark a finding as an exception so it no | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/mark-a-finding-as-an-exception-so-it-no-longer-appears-in-the-active-scan-results-list

/openapi.json post /v1/cloud-security/findings/{findingId}/exception
Accepts session, API key, or service token auth. For API key / service token callers without an explicit user attribution, the action is attributed to the.



# Resolve a GCP setup step | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/resolve-a-gcp-setup-step

/openapi.json post /v1/cloud-security/setup-gcp/{connectionId}/resolve-step
Resolve a GCP setup step in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings, and connect cloud posture.



# Resolve short-lived AWS credentials for a | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/resolve-short-lived-aws-credentials-for-a-connection-internal-only

/openapi.json post /v1/cloud-security/resolve-session/{connectionId}
Resolve short-lived AWS credentials for a connection (internal only) in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services.



# Resolve the "About this check" description | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/resolve-the-"about-this-check"-description-for-a-finding-ai-cached-for-aws;-provider-derived-for-gcpazure

/openapi.json get /v1/cloud-security/findings/{findingId}/check-definition
Resolve the "About this check" description for a finding (AI-cached for AWS; provider-derived for GCP/Azure) in Comp AI. Run AWS, Azure, and GCP cloud.



# Revoke an exception, reopening the finding | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/revoke-an-exception-reopening-the-finding

/openapi.json delete /v1/cloud-security/exceptions/{exceptionId}
Accepts session, API key, or service token auth. For API key / service token callers without an explicit user attribution, the action is attributed to the.



# Run cloud security scan | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/run-cloud-security-scan

/openapi.json post /v1/cloud-security/scan/{connectionId}
Trigger a cloud security scan for a connected AWS, Azure, or GCP account and collect findings for compliance remediation.



# Select GCP projects for a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/select-gcp-projects-for-a-connection

/openapi.json post /v1/cloud-security/select-gcp-projects/{connectionId}
Select GCP projects for a connection in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings, and connect cloud.



# Set up Azure for a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/set-up-azure-for-a-connection

/openapi.json post /v1/cloud-security/setup-azure/{connectionId}
Set up Azure for a connection in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings, and connect cloud posture.



# Set up GCP for a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/set-up-gcp-for-a-connection

/openapi.json post /v1/cloud-security/setup-gcp/{connectionId}
Set up GCP for a connection in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings, and connect cloud posture.



# Switch the AWS scan engine for a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/switch-the-aws-scan-engine-for-a-connection-comp-ai-scanners-↔-security-hub

/openapi.json patch /v1/cloud-security/connections/{connectionId}/scan-mode
Accepts session, API key, or service token auth. For API key / service token callers without an explicit user attribution, the action is attributed to the.



# Trigger a cloud security run for a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/trigger-a-cloud-security-run-for-a-connection

/openapi.json post /v1/cloud-security/trigger/{connectionId}
Trigger a cloud security run for a connection in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings.



# Validate Azure credentials for a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/cloudsecurity/validate-azure-credentials-for-a-connection

/openapi.json post /v1/cloud-security/validate-azure/{connectionId}
Validate Azure credentials for a connection in Comp AI. Run AWS, Azure, and GCP cloud security scans, detect enabled services, review findings, and connect.



# Create a new comment | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/comments/create-a-new-comment

/openapi.json post /v1/comments
Create a new comment in Comp AI. Create and manage collaboration comments on compliance entities such as tasks, policies, risks, vendors, and findings.



# Delete a comment | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/comments/delete-a-comment

/openapi.json delete /v1/comments/{commentId}
Delete a comment and all its attachments. Allowed for the comment author, or for a caller holding organization:update (owner/admin) moderating another.



# Get comments for an entity | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/comments/get-comments-for-an-entity

/openapi.json get /v1/comments
Get comments for an entity in Comp AI. Create and manage collaboration comments on compliance entities such as tasks, policies, risks, vendors, and findings.



# Update a comment | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/comments/update-a-comment

/openapi.json put /v1/comments/{commentId}
Update a comment in Comp AI. Create and manage collaboration comments on compliance entities such as tasks, policies, risks, vendors, and findings.



# Create a new context entry | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/context/create-a-new-context-entry

/openapi.json post /v1/context
Creates a new context entry for the authenticated organization. All required fields must be provided.



# Delete context entry | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/context/delete-context-entry

/openapi.json delete /v1/context/{id}
Permanently removes a context entry from the organization. This action cannot be undone.



# Get organization context | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/context/get-organization-context

/openapi.json get /v1/context/{id}
Retrieve one organization context entry with source details and approved content for compliance automation workflows.



# List organization context | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/context/list-organization-context

/openapi.json get /v1/context
List organization context entries used as approved source material for evidence, questionnaires, policies, and AI workflows.



# Update organization context | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/context/update-organization-context

/openapi.json patch /v1/context/{id}
Update an organization context entry so approved business details stay current for evidence and questionnaire automation.



# Create compliance control | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/create-compliance-control

/openapi.json post /v1/controls
Create a custom compliance control and connect it to framework requirements, policies, tasks, and evidence expectations.



# Delete a control | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/delete-a-control

/openapi.json delete /v1/controls/{id}
Delete a control in Comp AI. Manage controls, map them to policies, tasks, framework requirements, and evidence document types, and track implementation.



# Get control detail with progress | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/get-control-detail-with-progress

/openapi.json get /v1/controls/{id}
Get control detail with progress in Comp AI. Manage controls, map them to policies, tasks, framework requirements, and evidence document types, and track.



# Get dropdown options for creating controls | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/get-dropdown-options-for-creating-controls

/openapi.json get /v1/controls/options
Get dropdown options for creating controls in Comp AI. Manage controls, map them to policies, tasks, framework requirements, and evidence document types.



# Link existing requirements to a control | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/link-existing-requirements-to-a-control

/openapi.json post /v1/controls/{id}/requirements/link
Link existing requirements to a control in Comp AI. Manage controls, map them to policies, tasks, framework requirements, and evidence document types.



# Link policies to control | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/link-policies-to-control

/openapi.json post /v1/controls/{id}/policies/link
Link policies to a control so auditors and reviewers can trace control implementation back to approved policy evidence.



# Link required document types to a control | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/link-required-document-types-to-a-control

/openapi.json post /v1/controls/{id}/document-types/link
Link required document types to a control in Comp AI. Manage controls, map them to policies, tasks, framework requirements, and evidence document types.



# Link tasks to control | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/link-tasks-to-control

/openapi.json post /v1/controls/{id}/tasks/link
Link compliance tasks to a control so implementation work, evidence collection, and review status stay connected.



# List compliance controls | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/list-compliance-controls

/openapi.json get /v1/controls
List controls with linked policies, tasks, requirements, and document types for SOC 2, ISO 27001, HIPAA, and GDPR programs.



# Remove a required document type from a control | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/remove-a-required-document-type-from-a-control

/openapi.json delete /v1/controls/{id}/document-types/{formType}
Remove a required document type from a control in Comp AI. Manage controls, map them to policies, tasks, framework requirements, and evidence document.



# Unlink a task from a control | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/unlink-a-task-from-a-control

/openapi.json delete /v1/controls/{id}/tasks/{taskId}
Removes a task↔control link. With ?frameworkInstanceId, only that framework instance's link is removed; otherwise the org-wide link and derived.



# Unlink requirements from a control | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/unlink-requirements-from-a-control

/openapi.json delete /v1/controls/{id}/requirements/link
Removes requirement↔control links. Body mirrors POST requirements/link: each item sets frameworkInstanceId and exactly one of requirementId.



# Update a control | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/controls/update-a-control

/openapi.json patch /v1/controls/{id}
Updates org-editable control fields (name, description, review dates). Edits on template-managed controls are preserved by framework syncs. Use to reword.



# Check a device-agent update's metadata | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/check-a-device-agent-updates-metadata

/openapi.json head /v1/device-agent/updates/{filename}
Check a device-agent update's metadata in Comp AI. Register employee devices, submit device compliance check-ins, download agent builds, and manage endpoint.



# Create a device-agent auth code | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/create-a-device-agent-auth-code

/openapi.json post /v1/device-agent/auth-code
Create a device-agent auth code in Comp AI. Register employee devices, submit device compliance check-ins, download agent builds, and manage endpoint.



# Download a device-agent update | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/download-a-device-agent-update

/openapi.json get /v1/device-agent/updates/{filename}
Download a device-agent update in Comp AI. Register employee devices, submit device compliance check-ins, download agent builds, and manage endpoint.



# Download macOS Device Agent | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/download-macos-device-agent

/openapi.json get /v1/device-agent/mac
Downloads the Comp AI Device Agent installer for macOS as a DMG file. The agent helps monitor device compliance and security policies.



# Download Windows Device Agent ZIP | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/download-windows-device-agent-zip

/openapi.json get /v1/device-agent/windows
Downloads a ZIP package containing the Comp AI Device Agent installer for Windows, along with setup scripts and instructions. The package includes an MSI.



# Exchange an auth code for device credentials | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/exchange-an-auth-code-for-device-credentials

/openapi.json post /v1/device-agent/exchange-code
Exchange an auth code for device credentials in Comp AI. Register employee devices, submit device compliance check-ins, download agent builds, and manage.



# Get device-agent status | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/get-device-agent-status

/openapi.json get /v1/device-agent/status
Get device-agent status in Comp AI. Register employee devices, submit device compliance check-ins, download agent builds, and manage endpoint security status.



# List organizations for the current device | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/list-organizations-for-the-current-device

/openapi.json get /v1/device-agent/my-organizations
List organizations for the current device in Comp AI. Register employee devices, submit device compliance check-ins, download agent builds, and manage.



# Register device agent | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/register-device-agent

/openapi.json post /v1/device-agent/register
Register a Comp AI Device Agent installation so employee endpoint checks can report into compliance tasks and device inventory.



# Revoke a device agent session | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/revoke-a-device-agent-session

/openapi.json delete /v1/device-agent/sessions/{deviceId}
Revoke a device agent session in Comp AI. Register employee devices, submit device compliance check-ins, download agent builds, and manage endpoint security.



# Submit device compliance check-in | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/device-agent/submit-device-compliance-check-in

/openapi.json post /v1/device-agent/check-in
Submit device security check results for encryption, antivirus, password policy, screen lock, and other endpoint controls.



# Delete device | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/devices/delete-device

/openapi.json delete /v1/devices/{id}
Deletes a single device in the authenticated organization. Requires the member:delete permission (owners, admins, and custom roles with it).



# Get devices by member ID | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/devices/get-devices-by-member-id

/openapi.json get /v1/devices/member/{memberId}
Returns all devices assigned to a specific member within the authenticated organization. Devices are fetched from FleetDM using the member's dedicated.



# List managed devices | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/devices/list-managed-devices

/openapi.json get /v1/devices
List managed employee devices with endpoint compliance status, ownership, and security check results for workforce controls.



# Trigger bulk evidence export (Auditor only) | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-export-auditor/trigger-bulk-evidence-export-auditor-only

/openapi.json post /v1/evidence-export/all
Starts a background job that generates a ZIP of all evidence. Returns a run ID for progress tracking. Pass `from`/`to` to scope the export to an audit.



# Export automation evidence as PDF | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-export/export-automation-evidence-as-pdf

/openapi.json get /v1/tasks/{taskId}/evidence/automation/{automationId}/pdf
Export automation evidence as PDF in Comp AI. Export task evidence, automation evidence, and reviewer-ready evidence bundles as PDF or ZIP files.



# Export task evidence as ZIP | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-export/export-task-evidence-as-zip

/openapi.json get /v1/tasks/{taskId}/evidence/export
Download a ZIP package containing task evidence and automation results for auditor review or customer security requests.



# Get task evidence summary | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-export/get-task-evidence-summary

/openapi.json get /v1/tasks/{taskId}/evidence
Get task evidence summary in Comp AI. Export task evidence, automation evidence, and reviewer-ready evidence bundles as PDF or ZIP files.



# Delete a submission | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/delete-a-submission

/openapi.json delete /v1/evidence-forms/{formType}/submissions/{submissionId}
Delete a submission in Comp AI. Collect, review, upload, and export structured evidence submissions for compliance tasks and document requirements.



# Export evidence submissions | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/export-evidence-submissions

/openapi.json get /v1/evidence-forms/{formType}/export.csv
Export evidence form submissions as CSV for auditor requests, offline review, or internal compliance reporting.



# Get a single submission | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/get-a-single-submission

/openapi.json get /v1/evidence-forms/{formType}/submissions/{submissionId}
Get a single submission in Comp AI. Collect, review, upload, and export structured evidence submissions for compliance tasks and document requirements.



# Get current user submissions | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/get-current-user-submissions

/openapi.json get /v1/evidence-forms/my-submissions
Get current user submissions in Comp AI. Collect, review, upload, and export structured evidence submissions for compliance tasks and document requirements.



# Get document relevance settings | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/get-document-relevance-settings

/openapi.json get /v1/evidence-forms/settings
Get document relevance settings in Comp AI. Collect, review, upload, and export structured evidence submissions for compliance tasks and document.



# Get form definition and submissions | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/get-form-definition-and-submissions

/openapi.json get /v1/evidence-forms/{formType}
Get form definition and submissions in Comp AI. Collect, review, upload, and export structured evidence submissions for compliance tasks and document.



# Get pending submission count for current user | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/get-pending-submission-count-for-current-user

/openapi.json get /v1/evidence-forms/my-submissions/pending-count
Get pending submission count for current user in Comp AI. Collect, review, upload, and export structured evidence submissions for compliance tasks.



# Get submission statuses for all forms | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/get-submission-statuses-for-all-forms

/openapi.json get /v1/evidence-forms/statuses
Get submission statuses for all forms in Comp AI. Collect, review, upload, and export structured evidence submissions for compliance tasks and document.



# List evidence form submissions | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/list-evidence-form-submissions

/openapi.json get /v1/evidence-forms/{formType}/submissions
Returns the organization's submissions for one evidence form type in the standard {data, count} envelope, newest first. Use to audit evidence completeness.



# List evidence forms | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/list-evidence-forms

/openapi.json get /v1/evidence-forms
List structured evidence forms that collect recurring submissions for security, HR, IT, finance, and compliance workflows.



# Review evidence submission | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/review-evidence-submission

/openapi.json patch /v1/evidence-forms/{formType}/submissions/{submissionId}/review
Approve or reject a submitted evidence form so task status and audit readiness reflect the latest review decision.



# Submit evidence form | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/submit-evidence-form

/openapi.json post /v1/evidence-forms/{formType}/submissions
Submit structured evidence responses and attachments for review against a compliance task or document requirement.



# Update document relevance setting | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/update-document-relevance-setting

/openapi.json patch /v1/evidence-forms/{formType}/settings
Marks an evidence form as relevant or not relevant. Send notRelevantReason with each not-relevant mark; auditors expect one.



# Upload a file as an evidence submission | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/upload-a-file-as-an-evidence-submission

/openapi.json post /v1/evidence-forms/{formType}/upload-submission
Upload a file and create a submission for the given form type, bypassing form-specific validation. Provide exactly one of fileData (base64) or s3Key.



# Upload evidence form file | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/evidence-forms/upload-evidence-form-file

/openapi.json post /v1/evidence-forms/uploads
Upload one file for a form `file` field and get back the {fileName, fileKey, downloadUrl} object to send under that field key. Provide exactly one of.



# Create audit finding | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/findings/create-audit-finding

/openapi.json post /v1/findings
Create an audit finding so teams can track issue ownership, remediation activity, severity, and supporting evidence.



# Delete a finding (auditor or platform admin | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/findings/delete-a-finding-auditor-or-platform-admin-only

/openapi.json delete /v1/findings/{id}
Delete a finding (auditor or platform admin only) in Comp AI. Create, review, update, and track audit findings, remediation activity, and finding history.



# Get activity history for a finding | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/findings/get-activity-history-for-a-finding

/openapi.json get /v1/findings/{id}/history
Get activity history for a finding in Comp AI. Create, review, update, and track audit findings, remediation activity, and finding history for an.



# Get finding by ID | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/findings/get-finding-by-id

/openapi.json get /v1/findings/{id}
Get finding by ID in Comp AI. Create, review, update, and track audit findings, remediation activity, and finding history for an organization.



# List all findings for the organization | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/findings/list-all-findings-for-the-organization

/openapi.json get /v1/findings/organization
List all findings for the organization in Comp AI. Create, review, update, and track audit findings, remediation activity, and finding history for an.



# List audit findings | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/findings/list-audit-findings

/openapi.json get /v1/findings
List audit findings with status, severity, owner, history, and remediation context for compliance review workflows.



# Update a finding (status transition rules | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/findings/update-a-finding-status-transition-rules-apply

/openapi.json patch /v1/findings/{id}
Update a finding (status transition rules apply) in Comp AI. Create, review, update, and track audit findings, remediation activity, and finding history.



# Add a custom requirement to a framework | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/add-a-custom-requirement-to-a-framework-instance

/openapi.json post /v1/frameworks/{id}/requirements
Add a custom requirement to a framework instance in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores.



# Add compliance frameworks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/add-compliance-frameworks

/openapi.json post /v1/frameworks
Add one or more compliance frameworks to an organization so tasks, controls, evidence, and readiness tracking can be generated.



# Create a custom framework for this | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/create-a-custom-framework-for-this-organization

/openapi.json post /v1/frameworks/custom
Create a custom framework for this organization in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores.



# Delete a framework instance | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/delete-a-framework-instance

/openapi.json delete /v1/frameworks/{id}
Delete a framework instance in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores, and sync history.



# Get a single framework instance with full | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/get-a-single-framework-instance-with-full-detail

/openapi.json get /v1/frameworks/{id}
Get a single framework instance with full detail in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores.



# Get a specific requirement with related | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/get-a-specific-requirement-with-related-controls

/openapi.json get /v1/frameworks/{id}/requirements/{requirementKey}
Get a specific requirement with related controls in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores.



# Get framework readiness scores | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/get-framework-readiness-scores

/openapi.json get /v1/frameworks/scores
Retrieve framework readiness scores so teams can report progress toward audit readiness across active compliance standards.



# Get sync history for a framework instance | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/get-sync-history-for-a-framework-instance

/openapi.json get /v1/frameworks/{id}/sync-history
Get sync history for a framework instance in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores, and sync.



# Get the update status for a framework instance | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/get-the-update-status-for-a-framework-instance

/openapi.json get /v1/frameworks/{id}/update-status
Get the update status for a framework instance in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores.



# Get update statuses for all framework | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/get-update-statuses-for-all-framework-instances

/openapi.json get /v1/frameworks/update-statuses
Get update statuses for all framework instances in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores.



# Link (clone) existing requirements from | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/link-clone-existing-requirements-from-another-framework-into-this-one

/openapi.json post /v1/frameworks/{id}/requirements/link
Link (clone) existing requirements from another framework into this one in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances.



# Link existing org controls to a requirement | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/link-existing-org-controls-to-a-requirement

/openapi.json post /v1/frameworks/{id}/requirements/{requirementKey}/controls/link
Link existing org controls to a requirement in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores, and sync.



# List available frameworks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/list-available-frameworks

/openapi.json get /v1/frameworks/available
List frameworks available for activation before starting a new compliance program or expanding into another standard.



# List compliance frameworks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/list-compliance-frameworks

/openapi.json get /v1/frameworks
List active SOC 2, ISO 27001, HIPAA, GDPR, and custom compliance frameworks with implementation status and progress data.



# Preview changes from updating a framework | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/preview-changes-from-updating-a-framework-instance

/openapi.json get /v1/frameworks/{id}/update-preview
Preview changes from updating a framework instance in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores.



# Roll back a framework sync operation | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/roll-back-a-framework-sync-operation

/openapi.json post /v1/frameworks/{id}/rollback
Roll back a framework sync operation in Comp AI. Manage SOC 2, ISO 27001, HIPAA, GDPR, and custom framework instances, requirements, scores, and sync history.



# Sync framework requirements | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/sync-framework-requirements

/openapi.json post /v1/frameworks/{id}/sync
Sync framework requirements, controls, and tasks after framework content changes so compliance tracking remains current.



# Unlink controls from a requirement on a | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/unlink-controls-from-a-requirement-on-a-framework-instance

/openapi.json delete /v1/frameworks/{id}/requirements/{requirementKey}/controls/link
Removes control↔requirement links on this framework instance. Works for platform and custom requirements. Idempotent — returns the number of links removed.



# Update a custom framework | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/frameworks/update-a-custom-framework

/openapi.json patch /v1/frameworks/{id}/custom
Update the name and/or description of an organization's custom framework. Only custom frameworks are editable; platform frameworks return 400.



# Add a catalog threat as a risk on an asset | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/add-a-catalog-threat-as-a-risk-on-an-asset

/openapi.json post /v1/hipaa/risk-assessment/risks/from-template
Creates a register risk from a threat catalog entry, pre-filled with the threat, vulnerability and default rating, linked to the given ePHI asset.



# Check whether the HIPAA Security Risk | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/check-whether-the-hipaa-security-risk-assessment-is-available

/openapi.json get /v1/hipaa/risk-assessment/availability
Returns enabled: true when the organization has the HIPAA framework and can use the Security Risk Assessment. Read-only and side-effect free; needs only.



# Download a published HIPAA Security Risk | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/download-a-published-hipaa-security-risk-assessment-version

/openapi.json get /v1/hipaa/risk-assessment/versions/{id}/download
Downloads a signed-off version exactly as published, as PDF (default) or DOCX. Never reflects changes made after publication.



# Export the current HIPAA Security Risk | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/export-the-current-hipaa-security-risk-assessment

/openapi.json post /v1/hipaa/risk-assessment/export
Downloads the live, unpublished assessment as PDF or DOCX for preview. For the signed-off document use the versions endpoints.



# Get the HIPAA risk analysis rows | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/get-the-hipaa-risk-analysis-rows

/openapi.json get /v1/hipaa/risk-assessment/analysis
Returns the ePHI inventory rows and the risks linked to them as they will appear in the assessment: references, lifecycle, threats, vulnerabilities.



# Get the HIPAA Security Risk Assessment | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/get-the-hipaa-security-risk-assessment

/openapi.json get /v1/hipaa/risk-assessment
Returns the organization's HIPAA Security Risk Assessment: narrative, scope facts, inventory and risk counts, readiness to publish, changes since the last.



# List ePHI asset suggestions | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/list-ephi-asset-suggestions

/openapi.json get /v1/hipaa/risk-assessment/suggestions
Proposes ePHI inventory entries from vendors, connected integrations, enrolled devices and onboarding answers. Apply one by creating an asset with its key.



# List published HIPAA Security Risk Assessment | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/list-published-hipaa-security-risk-assessment-versions

/openapi.json get /v1/hipaa/risk-assessment/versions
Lists the signed-off versions of the assessment, oldest first, with publication date, signatory, notes and whether stored PDF and DOCX renders exist.



# List suggested HIPAA risks from the threat | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/list-suggested-hipaa-risks-from-the-threat-library

/openapi.json get /v1/hipaa/risk-assessment/risks/suggestions
Matches every catalog threat to the ePHI assets it applies to and proposes the risks to seed (10-15 for a typical inventory). Threats already covered by a.



# List the HIPAA threat catalog | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/list-the-hipaa-threat-catalog

/openapi.json get /v1/hipaa/risk-assessment/threat-catalog
Returns the catalog of reasonably anticipated threats to ePHI (threat, vulnerability, safeguards to confirm, default rating). Use an entry id with POST.



# Publish and sign off the HIPAA Security Risk | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/publish-and-sign-off-the-hipaa-security-risk-assessment

/openapi.json post /v1/hipaa/risk-assessment/versions
Freezes the current inventory, analysis and treatments as the next signed-off version, renders PDF and DOCX for retention, and sets the next review date.



# Seed the HIPAA threat library as risks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/seed-the-hipaa-threat-library-as-risks

/openapi.json post /v1/hipaa/risk-assessment/risks/seed
Creates one register risk per suggested threat, linked to every ePHI asset it applies to, and links existing same-titled risks instead of duplicating them.



# Update the HIPAA Security Risk Assessment | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/hipaa-security-risk-assessment/update-the-hipaa-security-risk-assessment

/openapi.json patch /v1/hipaa/risk-assessment
Edits the narrative sections (purpose, scope, methodology, roles, review triggers) or the review cadence. Omitted sections keep their text. Returns the.



# Create integration connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/create-integration-connection

/openapi.json post /v1/integrations/connections
Create an integration connection so Comp AI can collect evidence, run checks, or sync data from a connected provider.



# Delete an integration connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/delete-an-integration-connection

/openapi.json delete /v1/integrations/connections/{id}
Delete an integration connection in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Disconnect an integration | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/disconnect-an-integration

/openapi.json post /v1/integrations/connections/{id}/disconnect
Disconnect an integration in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# Disconnect checks from a task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/disconnect-checks-from-a-task

/openapi.json post /v1/integrations/tasks/{taskId}/checks/disconnect
Disconnect checks from a task in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# Get an integration connection by ID | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/get-an-integration-connection-by-id

/openapi.json get /v1/integrations/connections/{id}
Get an integration connection by ID in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Get an integration provider by slug | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/get-an-integration-provider-by-slug

/openapi.json get /v1/integrations/connections/providers/{slug}
Get an integration provider by slug in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Get Google Workspace sync status | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/get-google-workspace-sync-status

/openapi.json post /v1/integrations/sync/google-workspace/status
Get Google Workspace sync status in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Get JumpCloud sync status | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/get-jumpcloud-sync-status

/openapi.json post /v1/integrations/sync/jumpcloud/status
Get JumpCloud sync status in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# Get options for a connection variable | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/get-options-for-a-connection-variable

/openapi.json get /v1/integrations/variables/connections/{connectionId}/options/{variableId}
Get options for a connection variable in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Get the configured 2FA source provider | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/get-the-configured-2fa-source-provider

/openapi.json get /v1/integrations/sync/two-factor-source
Get the configured 2FA source provider in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Get the currently configured device sync | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/get-the-currently-configured-device-sync-provider

/openapi.json get /v1/integrations/sync/device-sync-provider
Get the currently configured device sync provider in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage.



# Get the currently configured employee sync | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/get-the-currently-configured-employee-sync-provider

/openapi.json get /v1/integrations/sync/employee-sync-provider
Get the currently configured employee sync provider in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage.



# List a check run's results | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-a-check-runs-results

/openapi.json get /v1/integrations/tasks/{taskId}/runs/{runId}/results
Returns one page of a check run's per-resource results (findings and passing rows) for a task. The run list only carries a small sample per run; use this.



# List check definitions for a provider | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-check-definitions-for-a-provider

/openapi.json get /v1/integrations/checks/providers/{providerSlug}
List check definitions for a provider in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# List check runs for a task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-check-runs-for-a-task

/openapi.json get /v1/integrations/tasks/{taskId}/runs
List check runs for a task in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# List checks attached to a task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-checks-attached-to-a-task

/openapi.json get /v1/integrations/tasks/{taskId}/checks
List checks attached to a task in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# List checks for a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-checks-for-a-connection

/openapi.json get /v1/integrations/checks/connections/{connectionId}
List checks for a connection in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# List checks for a task template | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-checks-for-a-task-template

/openapi.json get /v1/integrations/tasks/template/{templateId}/checks
List checks for a task template in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# List connection variables | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-connection-variables

/openapi.json get /v1/integrations/variables/connections/{connectionId}
List connection variables in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# List integration connections | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-integration-connections

/openapi.json get /v1/integrations/connections
List integration connections in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# List integration providers | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-integration-providers

/openapi.json get /v1/integrations/connections/providers
List available integration providers that can connect to the organization for automated evidence collection and compliance checks.



# List integrations that can supply per-user | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-integrations-that-can-supply-per-user-2fa-status

/openapi.json get /v1/integrations/sync/available-2fa-sources
List integrations that can supply per-user 2FA status in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees.



# List services enabled on a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-services-enabled-on-a-connection

/openapi.json get /v1/integrations/connections/{id}/services
List services enabled on a connection in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# List sync providers available to the org | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-sync-providers-available-to-the-org

/openapi.json get /v1/integrations/sync/available-providers
List sync providers available to the org in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# List variable definitions for a provider | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/list-variable-definitions-for-a-provider

/openapi.json get /v1/integrations/variables/providers/{providerSlug}
List variable definitions for a provider in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Pause an integration connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/pause-an-integration-connection

/openapi.json post /v1/integrations/connections/{id}/pause
Pause an integration connection in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Per-user 2FA status from the configured source | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/per-user-2fa-status-from-the-configured-source

/openapi.json get /v1/integrations/sync/two-factor-statuses
Per-user 2FA status from the configured source in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage.



# Reconnect checks to a task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/reconnect-checks-to-a-task

/openapi.json post /v1/integrations/tasks/{taskId}/checks/reconnect
Reconnect checks to a task in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# Resume an integration connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/resume-an-integration-connection

/openapi.json post /v1/integrations/connections/{id}/resume
Resume an integration connection in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Run a check for a task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/run-a-check-for-a-task

/openapi.json post /v1/integrations/tasks/{taskId}/run-check
Run a check for a task in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# Run a single check on a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/run-a-single-check-on-a-connection

/openapi.json post /v1/integrations/checks/connections/{connectionId}/run/{checkId}
Run a single check on a connection in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Run integration checks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/run-integration-checks

/openapi.json post /v1/integrations/checks/connections/{connectionId}/run
Run all compliance checks for an integration connection and capture results as automated evidence.



# Set services enabled on a connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/set-services-enabled-on-a-connection

/openapi.json put /v1/integrations/connections/{id}/services
Set services enabled on a connection in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Set the 2FA source provider | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/set-the-2fa-source-provider

/openapi.json post /v1/integrations/sync/two-factor-source
Set the 2FA source provider in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# Set the device sync provider | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/set-the-device-sync-provider

/openapi.json post /v1/integrations/sync/device-sync-provider
Set the device sync provider in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# Set the employee sync provider | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/set-the-employee-sync-provider

/openapi.json post /v1/integrations/sync/employee-sync-provider
Set the employee sync provider in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Sync devices for a dynamic provider | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/sync-devices-for-a-dynamic-provider

/openapi.json post /v1/integrations/sync/dynamic/{providerSlug}/devices
Sync devices for a dynamic provider in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Sync employees for a dynamic provider | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/sync-employees-for-a-dynamic-provider

/openapi.json post /v1/integrations/sync/dynamic/{providerSlug}/employees
Sync employees for a dynamic provider in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Sync Google Workspace employees | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/sync-google-workspace-employees

/openapi.json post /v1/integrations/sync/google-workspace/employees
Sync Google Workspace employees in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Sync JumpCloud employees | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/sync-jumpcloud-employees

/openapi.json post /v1/integrations/sync/jumpcloud/employees
Sync JumpCloud employees in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# Test an integration connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/test-an-integration-connection

/openapi.json post /v1/integrations/connections/{id}/test
Test an integration connection in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Update an integration connection | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/update-an-integration-connection

/openapi.json patch /v1/integrations/connections/{id}
Update an integration connection in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables.



# Update connection variables | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/integrations/update-connection-variables

/openapi.json post /v1/integrations/variables/connections/{connectionId}
Update connection variables in Comp AI. Connect vendor systems, configure OAuth apps, run compliance checks, sync employees, manage variables, and collect.



# Add vendors to the Approved Software Register | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/add-vendors-to-the-approved-software-register-in-one-action

/openapi.json post /v1/isms/documents/{id}/approved-software/import-vendors
Adds the chosen vendors as approved software rows in one transaction. Vendors already listed are skipped, not duplicated. "Where it is used" is left.



# Add vendors to the continuity contact list in | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/add-vendors-to-the-continuity-contact-list-in-one-action

/openapi.json post /v1/isms/documents/{id}/continuity-contacts/import-vendors
Adds the chosen vendors to the Business Continuity Plan contact list in one transaction. Vendors already listed are skipped, not duplicated. The support.



# Approve an ISMS document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/approve-an-isms-document

/openapi.json post /v1/isms/documents/{id}/approve
Approves an ISMS document that is pending review, freezing an immutable published version with PDF and DOCX renders. Only the assigned approver can call it.



# Create a row in an ISMS register | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/create-a-row-in-an-isms-register

/openapi.json post /v1/isms/documents/{id}/registers/{register}
Create a row in an ISMS register in Comp AI. Build and maintain the ISO 27001 ISMS document set — scope, leadership commitment, context, interested parties.



# Decline an ISMS document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/decline-an-isms-document

/openapi.json post /v1/isms/documents/{id}/decline
Rejects an ISMS document that is pending review, setting its status to declined without creating a version. Only the assigned approver can call it, using a.



# Delete a row in an ISMS register | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/delete-a-row-in-an-isms-register

/openapi.json delete /v1/isms/registers/{register}/{rowId}
Permanently deletes one row from an ISMS register, and cascades: deleting an audit removes its controls and findings, and deleting a metric removes its.



# Derive Context-of-the-Organization issues | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/derive-context-of-the-organization-issues

/openapi.json post /v1/isms/documents/{id}/generate
Regenerates one ISMS document's derived content based on its type and refreshes the drift baseline. Manually added register rows and non-empty narratives.



# Detect drift against the approved snapshot | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/detect-drift-against-the-approved-snapshot

/openapi.json get /v1/isms/documents/{id}/drift
Reports whether an ISMS document's derived content is stale by comparing the platform data captured at its last generation against current data. Returns.



# Ensure ISMS foundational documents exist | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/ensure-isms-foundational-documents-exist

/openapi.json post /v1/isms/ensure-setup
Lists the organization's twelve ISO 27001 ISMS documents and creates any that are missing, returning each id, type and status. This is the only way.



# Export an ISMS document as PDF or DOCX | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/export-an-isms-document-as-pdf-or-docx

/openapi.json post /v1/isms/documents/{id}/export
Downloads an ISMS document as PDF or DOCX rather than JSON. Defaults to the latest published version; pass a versionId for a specific historical version.



# Get an ISMS document with its latest version | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/get-an-isms-document-with-its-latest-version

/openapi.json get /v1/isms/documents/{id}
Returns one ISMS document with every register expanded — context issues, interested parties, objectives, roles, metrics, audits, reviews and linked controls.



# List an ISMS document's published version | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/list-an-isms-documents-published-version-history

/openapi.json get /v1/isms/documents/{id}/versions
Lists an ISMS document's published versions newest first with version number, publication date, publisher, and whether PDF or DOCX renders exist. Versions.



# Map organization controls to an ISMS document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/map-organization-controls-to-an-isms-document

/openapi.json post /v1/isms/documents/{id}/controls
Links existing organization controls to an ISMS document by control id. Additive and idempotent — re-linking is a no-op. Returns a confirmation message.



# Raise register entries from internal-audit | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/raise-register-entries-from-internal-audit-findings

/openapi.json post /v1/isms/documents/{id}/nonconformities/import-findings
Raises the chosen internal-audit findings as entries in the Nonconformity & Corrective Action Register, in one transaction. A finding already imported is.



# Record measurements for several metrics/period | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/record-measurements-for-several-metricsperiods-in-one-save-metrics-due-backfill

/openapi.json post /v1/isms/documents/{id}/measurements/bulk
Record measurements for several metrics/periods in one save (Metrics due / backfill) in Comp AI. Build and maintain the ISO 27001 ISMS document set — scope.



# Remove a control mapping from an ISMS document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/remove-a-control-mapping-from-an-isms-document

/openapi.json delete /v1/isms/documents/{id}/controls/{controlId}
Removes the mapping between an ISMS document and one organization control. Takes the control id, not the link row id. The control itself is not deleted.



# Remove an ISMS document's uploaded file | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/remove-an-isms-documents-uploaded-file

/openapi.json delete /v1/isms/documents/{id}/upload
Detaches the pending uploaded file from an ISMS document's draft. Already-published versions keep their own copy and stay downloadable. Returns the.



# Save a singleton document narrative | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/save-a-singleton-document-narrative

/openapi.json post /v1/isms/documents/{id}/narrative
Replaces the working draft narrative of a document type that stores one, such as ISMS scope, leadership commitment, internal audit or risk assessment.



# Set how much of an ISMS document Comp AI holds | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/set-how-much-of-an-isms-document-comp-ai-holds

/openapi.json post /v1/isms/documents/{id}/coverage
Marks an ISMS document, or one section of it, as included, maintained outside Comp AI, or not applicable, which requires a written justification. External.



# Submit an ISMS document for approval | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/submit-an-isms-document-for-approval

/openapi.json post /v1/isms/documents/{id}/submit-for-approval
Sends an ISMS document to a named approver for review, setting its status to needs_review. Requires the approverId of an active member. Rejected if any.



# Switch an ISMS document between form and | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/switch-an-isms-document-between-form-and-uploaded-file

/openapi.json patch /v1/isms/documents/{id}/content-source
Sets whether the document's content is 'generated' from our form or is the 'uploaded' customer file. Switching is lossless — the form data and the uploaded.



# The Risk Treatment Plan's rows (Clause 6.1.3) | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/the-risk-treatment-plans-rows-clause-613

/openapi.json get /v1/isms/documents/{id}/risk-treatment
Returns the organisational and supplier risk rows the Risk Treatment Plan renders (from the Risk Register and Vendors, with acceptance state per row) plus.



# Update a row in an ISMS register | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/update-a-row-in-an-isms-register

/openapi.json patch /v1/isms/registers/{register}/{rowId}
Updates one row in an ISMS register. Omitted fields are left unchanged and an explicit null clears a value, so omit rather than null to preserve it.



# Upload a file as an ISMS document's content | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/isms/upload-a-file-as-an-isms-documents-content

/openapi.json post /v1/isms/documents/{id}/upload
Attaches a customer-supplied PDF or DOCX as the document's content. Does not switch the document to it — call PATCH content-source with 'uploaded' for that.



# Delete a knowledge base document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/knowledge-base/delete-a-knowledge-base-document

/openapi.json post /v1/knowledge-base/documents/{documentId}/delete
Delete a knowledge base document in Comp AI. Upload source documents, process them for retrieval, and manage reusable manual answers that power.



# Delete a manual answer | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/knowledge-base/delete-a-manual-answer

/openapi.json post /v1/knowledge-base/manual-answers/{manualAnswerId}/delete
Delete a manual answer in Comp AI. Upload source documents, process them for retrieval, and manage reusable manual answers that power questionnaires and AI.



# Delete all manual answers for an organization | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/knowledge-base/delete-all-manual-answers-for-an-organization

/openapi.json post /v1/knowledge-base/manual-answers/delete-all
Delete all manual answers for an organization in Comp AI. Upload source documents, process them for retrieval, and manage reusable manual answers that power.



# Get a signed download URL for a document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/knowledge-base/get-a-signed-download-url-for-a-document

/openapi.json post /v1/knowledge-base/documents/{documentId}/download
Get a signed download URL for a document in Comp AI. Upload source documents, process them for retrieval, and manage reusable manual answers that power.



# Get a signed view URL for a document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/knowledge-base/get-a-signed-view-url-for-a-document

/openapi.json post /v1/knowledge-base/documents/{documentId}/view
Get a signed view URL for a document in Comp AI. Upload source documents, process them for retrieval, and manage reusable manual answers that power.



# List all manual answers for an organization | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/knowledge-base/list-all-manual-answers-for-an-organization

/openapi.json get /v1/knowledge-base/manual-answers
List all manual answers for an organization in Comp AI. Upload source documents, process them for retrieval, and manage reusable manual answers that power.



# List knowledge base documents | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/knowledge-base/list-knowledge-base-documents

/openapi.json get /v1/knowledge-base/documents
List uploaded knowledge base documents that Comp AI can use as approved source material for answers, policies, and reviews.



# Process knowledge base documents | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/knowledge-base/process-knowledge-base-documents

/openapi.json post /v1/knowledge-base/documents/process
Start document processing so uploaded knowledge base files become searchable source material for AI-assisted compliance workflows.



# Save reusable manual answer | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/knowledge-base/save-reusable-manual-answer

/openapi.json post /v1/knowledge-base/manual-answers
Save or update a reusable manual answer for security questionnaires that need approved, consistent response language.



# Upload knowledge base document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/knowledge-base/upload-knowledge-base-document

/openapi.json post /v1/knowledge-base/documents/upload
Upload supporting documentation so Comp AI can process approved source material for questionnaire answers and policy workflows.



# Download the engagement letter PDF | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/letter-of-engagement/download-the-engagement-letter-pdf

/openapi.json get /v1/letter-of-engagement/pdf
Renders the organization's Comp AI engagement letter as a PDF for sharing with auditors, customers and prospects. Returns 402 while the first subscription.



# Get the engagement letter | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/letter-of-engagement/get-the-engagement-letter

/openapi.json get /v1/letter-of-engagement
Returns the organization's Comp AI engagement letter: company name, website, active frameworks, trust portal URL, engagement date and the letter text, plus.



# Add an offboarding checklist template item | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/add-an-offboarding-checklist-template-item

/openapi.json post /v1/offboarding-checklist/template
Creates a new item in the organization's offboarding checklist template so it appears on every member's offboarding checklist from now on.



# Complete an offboarding checklist item | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/complete-an-offboarding-checklist-item

/openapi.json post /v1/offboarding-checklist/member/{memberId}/item/{templateItemId}/complete
Marks a specific offboarding checklist item complete for a member, recording who completed it and when, as part of finishing that member's offboarding.



# Confirm all vendor access as revoked | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/confirm-all-vendor-access-as-revoked

/openapi.json post /v1/offboarding-checklist/member/{memberId}/access-revocations/confirm-all
Marks every vendor access record for a departing member as revoked in one step, recording who confirmed it, to complete access removal during offboarding.



# Delete an offboarding checklist template item | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/delete-an-offboarding-checklist-template-item

/openapi.json delete /v1/offboarding-checklist/template/{id}
Removes an item from the organization's offboarding checklist template by id so it no longer appears on members' offboarding checklists.



# Export all offboarding evidence as a zip file | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/export-all-offboarding-evidence-as-a-zip-file

/openapi.json get /v1/offboarding-checklist/export-all
Exports a zip archive containing the offboarding checklist evidence for every member in the organization, for audits, handovers, or record-keeping.



# Export offboarding evidence as a zip file | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/export-offboarding-evidence-as-a-zip-file

/openapi.json get /v1/offboarding-checklist/member/{memberId}/export
Exports a zip archive of the offboarding checklist evidence collected for a single member, for audit, handover, or record-keeping purposes.



# Get a member's offboarding checklist | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/get-a-members-offboarding-checklist

/openapi.json get /v1/offboarding-checklist/member/{memberId}
Returns the offboarding checklist for a specific member, including each item and whether it has been completed, to track that person's offboarding progress.



# Get members with pending offboarding | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/get-members-with-pending-offboarding-checklists

/openapi.json get /v1/offboarding-checklist/pending
Lists members whose offboarding checklist is still incomplete, with their outstanding items, so you can track and finish departing-employee offboarding.



# Get the offboarding checklist template | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/get-the-offboarding-checklist-template

/openapi.json get /v1/offboarding-checklist/template
Returns the organization's offboarding checklist template: the ordered set of items every departing member must complete during their offboarding.



# Get vendor access revocation status for a | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/get-vendor-access-revocation-status-for-a-member

/openapi.json get /v1/offboarding-checklist/member/{memberId}/access-revocations
Lists the vendors a departing member had access to and whether each has been revoked, so you can confirm all vendor access is removed during offboarding.



# Mark vendor access as revoked | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/mark-vendor-access-as-revoked

/openapi.json post /v1/offboarding-checklist/member/{memberId}/access-revocations/{vendorId}
Marks a single vendor's access for a departing member as revoked, optionally attaching evidence and notes, as part of offboarding access removal.



# Reopen an offboarding checklist item | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/reopen-an-offboarding-checklist-item

/openapi.json delete /v1/offboarding-checklist/member/{memberId}/item/{templateItemId}/complete
Reverts a previously completed offboarding checklist item back to incomplete for a member, in case the step was marked done by mistake.



# Undo vendor access revocation | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/undo-vendor-access-revocation

/openapi.json delete /v1/offboarding-checklist/member/{memberId}/access-revocations/{vendorId}
Reverses a vendor access revocation for a member, marking that vendor's access as not revoked again, in case it was confirmed by mistake during offboarding.



# Update an offboarding checklist template item | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/update-an-offboarding-checklist-template-item

/openapi.json patch /v1/offboarding-checklist/template/{id}
Updates an existing offboarding checklist template item by id, changing its label, description, or settings on the organization's offboarding template.



# Upload evidence for an offboarding checklist | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/offboarding-checklist/upload-evidence-for-an-offboarding-checklist-item

/openapi.json post /v1/offboarding-checklist/member/{memberId}/item/{templateItemId}/evidence
Attaches a supporting evidence file to a member's completed offboarding checklist item, documenting that the offboarding step was actually carried out.



# Create or update an interactive organization | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/org-chart/create-or-update-an-interactive-organization-chart

/openapi.json put /v1/org-chart
Create or update an interactive organization chart in Comp AI. Manage organization chart metadata and evidence used for governance, accountability.



# Delete the organization chart | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/org-chart/delete-the-organization-chart

/openapi.json delete /v1/org-chart
Delete the organization chart in Comp AI. Manage organization chart metadata and evidence used for governance, accountability, and audit readiness.



# Get the organization chart | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/org-chart/get-the-organization-chart

/openapi.json get /v1/org-chart
Get the organization chart in Comp AI. Manage organization chart metadata and evidence used for governance, accountability, and audit readiness.



# Upload an image as the organization chart | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/org-chart/upload-an-image-as-the-organization-chart

/openapi.json post /v1/org-chart/upload
Upload an image as the organization chart in Comp AI. Manage organization chart metadata and evidence used for governance, accountability, and audit.



# Auto-approve organization access via domain | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/auto-approve-organization-access-via-domain-or-self-hosted-check

/openapi.json post /v1/organization-access/auto-approve
Grants hasAccess on the active organization if the requesting user is an internal trycomp.ai user, the deployment is self-hosted, or the user email domain.



# Create API key | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/create-api-key

/openapi.json post /v1/organization/api-keys
Create a scoped API key for server-side compliance automation such as evidence sync, policy workflows, or security questionnaire tooling.



# Delete organization | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/delete-organization

/openapi.json delete /v1/organization
Permanently deletes the authenticated organization. This action cannot be undone.



# Get organization brand color | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/get-organization-brand-color

/openapi.json get /v1/organization/primary-color
Retrieve the organization primary brand color used for Trust Center theming, portals, and API-driven embedded experiences.



# Get organization onboarding status | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/get-organization-onboarding-status

/openapi.json get /v1/organization/onboarding
Get organization onboarding status in Comp AI. Manage organization profile data, API keys, logos, ownership, role notifications, and access approval settings.



# Get organization profile | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/get-organization-profile

/openapi.json get /v1/organization
Retrieve organization profile data used to personalize compliance workflows, Trust Center branding, API automation, and audit readiness reporting.



# Get role notification settings | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/get-role-notification-settings

/openapi.json get /v1/organization/role-notifications
Get role notification settings in Comp AI. Manage organization profile data, API keys, logos, ownership, role notifications, and access approval settings.



# List API key scopes | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/list-api-key-scopes

/openapi.json get /v1/organization/api-keys/available-scopes
Retrieve available API key scopes and permissions before creating credentials for a specific compliance automation workflow.



# List API keys | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/list-api-keys

/openapi.json get /v1/organization/api-keys
List active API keys for an organization so administrators can audit automation access and rotate credentials safely.



# Remove organization logo | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/remove-organization-logo

/openapi.json delete /v1/organization/logo
Remove organization logo in Comp AI. Manage organization profile data, API keys, logos, ownership, role notifications, and access approval settings.



# Revoke API key | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/revoke-api-key

/openapi.json post /v1/organization/api-keys/revoke
Revoke an organization API key when an integration is retired, credentials rotate, or access should be removed.



# Transfer organization ownership | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/transfer-organization-ownership

/openapi.json post /v1/organization/transfer-ownership
Transfers organization ownership to another member. The current owner will become an admin and keep all other roles. The new owner will receive the owner.



# Update organization | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/update-organization

/openapi.json patch /v1/organization
Partially updates the authenticated organization. Only provided fields will be updated.



# Update role notification settings | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/update-role-notification-settings

/openapi.json put /v1/organization/role-notifications
Update role notification settings in Comp AI. Manage organization profile data, API keys, logos, ownership, role notifications, and access approval settings.



# Upload organization logo | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/organization/upload-organization-logo

/openapi.json post /v1/organization/logo
Upload organization logo in Comp AI. Manage organization profile data, API keys, logos, ownership, role notifications, and access approval settings.



# Compliance Automation API
Source: https://www.trycomp.ai/docs/api-reference/overview

Use the Comp AI API to automate SOC 2 evidence, policies, Trust Access, security questionnaires, tasks, and compliance workflows.

The Comp AI API lets engineering, security, and compliance teams connect their internal systems to the compliance workflows they run in Comp AI.

Use it to automate evidence collection, manage policies, coordinate compliance tasks, answer security questionnaires, configure Trust Center access, track risks and vendors, and keep SOC 2, ISO 27001, HIPAA, GDPR, and custom framework programs connected to the systems where work actually happens.

> **Prefer to drive Comp AI from an AI assistant?** The same endpoints documented here are also available as tools in the [Comp AI MCP Connector](/docs/mcp-connector) — add it to Claude, Cursor, ChatGPT, or any MCP-compatible client with one URL and a sign-in, then ask in plain language.

## Authentication

Most organization automation uses the `X-API-Key` header. Create scoped API keys inside your Comp AI organization, keep them server-side, and grant only the permissions needed for the workflow you are building.

```bash theme={null}
curl --request GET \
  --url "https://api.trycomp.ai/v1/organization" \
  --header "X-API-Key: $COMP_AI_API_KEY"
```

The reference covers Comp AI's product APIs across compliance operations, not just a single workflow. API-key backed endpoints are the integration contract for organization automation, while app session routes are kept out of the public reference.

* Trust Access management, public Trust Center data, evidence, policies, questionnaires, vendors, risks, integrations, cloud checks, and device compliance are API-backed workflows.
* Device Agent endpoints are used by signed-in employee devices.
* Webhook endpoints are intentionally omitted from the public reference unless they are useful for implementers.
* Internal, platform-admin, health, assistant, and browser automation routes are excluded from Mintlify docs.

## API Surface

| Area | What you can automate |
| - | - |
| Evidence and tasks | List compliance tasks, upload evidence, export audit-ready evidence bundles, and create recurring evidence automations. |
| Policies and knowledge base | Create, version, publish, export, and improve policies while keeping approved source material available for AI-assisted workflows. |
| Security questionnaires | Upload questionnaires, extract questions, generate answers from approved evidence, review edits, and export completed files. |
| Trust Center and Trust Access | Manage access requests, NDA signing, grants, document downloads, certificates, FAQs, custom links, and public overview content. |
| Frameworks and controls | Track framework readiness, map controls to policies, tasks, requirements, and evidence expectations. |
| Integrations and cloud checks | Connect providers, run compliance checks, trigger AWS, Azure, and GCP scans, and review cloud security findings. |
| People, devices, and training | Track workforce members, device compliance, training completions, and endpoint evidence for people-security controls. |
| Vendors, risks, and findings | Manage third-party risk, organizational risks, audit findings, remediation status, and supporting evidence. |
| Penetration tests | Create security assessment runs, track progress, inspect findings, and download report artifacts. |

## Common Workflows

> **[Automated evidence](/docs/automated-evidence)**
>
> Connect tasks to recurring evidence collection so audit proof stays current.

> **[Security questionnaire API](/docs/api-reference/questionnaire/upload-a-questionnaire-file-and-auto-answer-with-export)**
>
> Upload questionnaires, generate approved answers, and export reviewer-ready files.

> **[Policy workflows](/docs/ai-policy-editor)**
>
> Draft, version, publish, and export policies that support audits and customer reviews.

> **[Trust Access](/docs/trust-access)**
>
> Approve external reviewers, collect NDAs, and share controlled Trust Center resources.

> **[Integrations](/docs/integrations)**
>
> Connect SaaS, cloud, and security tools that provide continuous compliance evidence.

> **[Cloud tests](/docs/cloud-tests)**
>
> Run AWS, Azure, and GCP security checks and turn findings into remediation work.

> **[Device compliance](/docs/device-agent)**
>
> Register endpoints and submit device security check-ins for workforce controls.

> **[Penetration tests](/docs/penetration-tests)**
>
> Start security assessment runs and download report deliverables for review.

## Generated Reference Quality

The endpoint reference is generated from the NestJS OpenAPI specification used by the Comp AI API. Endpoint titles, descriptions, examples, visibility rules, and Mintlify metadata are maintained in the API source so generated pages stay aligned with product behavior as routes change.

Public customer-facing endpoints are documented. Internal operations, admin tooling, health checks, webhooks that are not useful for implementers, and routes that would expose private implementation details are intentionally excluded or hidden.

## Implementation Guidance

Start with the workflow you want to automate, then create a scoped API key for that workflow. For most teams, the first high-value integrations are:

1. Syncing evidence and task status into internal compliance reporting.
2. Uploading source documents to improve questionnaire and policy workflows.
3. Connecting Trust Center access approvals to CRM or customer-security processes.
4. Exporting evidence, policies, or questionnaire results for auditor and customer reviews.

Use production API calls against `https://api.trycomp.ai` and avoid storing API keys in client-side code.


# Add multiple members to organization | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/add-multiple-members-to-organization

/openapi.json post /v1/people/bulk
Bulk adds multiple members to the authenticated organization. Each member must have a valid user ID that exists in the system. Members who already exist in.



# Create a new member | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/create-a-new-member

/openapi.json post /v1/people
Adds a new member to the authenticated organization. The user must already exist in the system.



# Delete employment evidence | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/delete-employment-evidence

/openapi.json delete /v1/people/{id}/employment-evidence/{eventType}/{attachmentId}
Delete employment evidence in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences, and employee evidence.



# Delete member | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/delete-member

/openapi.json delete /v1/people/{id}
Permanently removes a member from the organization. This action cannot be undone.



# Get all employee devices with fleet | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/get-all-employee-devices-with-fleet-compliance-data

/openapi.json get /v1/people/devices
Get all employee devices with fleet compliance data in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences.



# Get current user email notification | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/get-current-user-email-notification-preferences

/openapi.json get /v1/people/me/email-preferences
Get current user email notification preferences in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences.



# Get employment evidence attachments | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/get-employment-evidence-attachments

/openapi.json get /v1/people/{id}/employment-evidence/{eventType}
Get employment evidence attachments in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences, and employee.



# Get fleet compliance | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/get-fleet-compliance

/openapi.json get /v1/people/{id}/fleet-compliance
Retrieve Fleet device compliance status so endpoint security findings can support people-security controls and audit evidence.



# Get integration test statistics grouped by | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/get-integration-test-statistics-grouped-by-assignee

/openapi.json get /v1/people/test-stats/by-assignee
Get integration test statistics grouped by assignee in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences.



# Get members who can read a specific resource | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/get-members-who-can-read-a-specific-resource-type

/openapi.json get /v1/people/mentionable
Get members who can read a specific resource type in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences.



# Get person by ID | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/get-person-by-id

/openapi.json get /v1/people/{id}
Returns a specific member by ID for the authenticated organization with their user information.



# Get training video completions for a member | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/get-training-video-completions-for-a-member

/openapi.json get /v1/people/{id}/training-videos
Get training video completions for a member in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences.



# Invite workforce members | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/invite-workforce-members

/openapi.json post /v1/people/invite
Invite employees or contractors to complete portal tasks, training, device setup, and compliance evidence requirements.



# List workforce members | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/list-workforce-members

/openapi.json get /v1/people
List employees and contractors with onboarding, training, device, and compliance status used for people-security controls.



# Member's access across connected integrations | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/members-access-across-connected-integrations

/openapi.json get /v1/people/{id}/access
Aggregates the latest Employee Access check results from every connected integration bound to the Employee Access task, matched to the member by email.



# Reactivate a deactivated member | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/reactivate-a-deactivated-member

/openapi.json patch /v1/people/{id}/reactivate
Reactivate a deactivated member in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences, and employee.



# Remove host (device) from Fleet | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/remove-host-device-from-fleet

/openapi.json delete /v1/people/{id}/host/{hostId}
Removes a single host (device) from FleetDM by host ID. Requires the member:delete permission (owners, admins, and custom roles with it). Validates the.



# Resend portal invite email to a member | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/resend-portal-invite-email-to-a-member

/openapi.json post /v1/people/{id}/resend-portal-invite
Resend portal invite email to a member in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences, and employee.



# Send a portal reminder to one member | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/send-a-portal-reminder-to-one-member

/openapi.json post /v1/people/{id}/send-reminder
Emails one member a reminder naming the policies they have not acknowledged and counting the training videos they have not finished. Fails if they owe.



# Send portal reminders in bulk | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/send-portal-reminders-in-bulk

/openapi.json post /v1/people/send-reminders
Emails a reminder to each listed member with outstanding policy acknowledgments or unfinished training. Omit memberIds entirely to cover the whole.



# Unlink device from member | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/unlink-device-from-member

/openapi.json patch /v1/people/{id}/unlink-device
Resets the fleetDmLabelId for a member, effectively unlinking their device from FleetDM. This will disconnect the device from the organization.



# Update current user email notification | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/update-current-user-email-notification-preferences

/openapi.json put /v1/people/me/email-preferences
Update current user email notification preferences in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences.



# Update workforce member | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/update-workforce-member

/openapi.json patch /v1/people/{id}
Update a workforce member profile, role, department, or compliance metadata used for people-security controls.



# Upload employment evidence | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/people/upload-employment-evidence

/openapi.json post /v1/people/{id}/employment-evidence/{eventType}
Upload employment evidence in Comp AI. Invite and manage workforce members, training status, device compliance, email preferences, and employee evidence.



# Accept pending policy changes and publish the | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/accept-pending-policy-changes-and-publish-the-version

/openapi.json post /v1/policies/{id}/accept-changes
Accept pending policy changes and publish the version in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted.



# Apply framework template updates to every | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/apply-framework-template-updates-to-every-policy-that-has-them

/openapi.json post /v1/policy-template-updates/apply
Stages each policy as a new draft version: their content plus the missing blocks. Published content and signatures are untouched. Declined policies are left.



# Apply framework template updates to one policy | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/apply-framework-template-updates-to-one-policy

/openapi.json post /v1/policy-template-updates/{id}/apply
Stages a new draft version: the policy as it stands plus the missing blocks. Published content and signatures are untouched. Naming a declined policy here.



# Chat with AI about a policy | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/chat-with-ai-about-a-policy

/openapi.json post /v1/policies/{id}/ai-chat
Ask policy-specific questions and request draft improvements while preserving human review before policy changes are applied.



# Confirm a policy PDF upload completed | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/confirm-a-policy-pdf-upload-completed

/openapi.json post /v1/policies/{id}/pdf/confirm
Links an uploaded PDF to a compliance policy after the file has been PUT to a presigned S3 URL. Call this after request-policy-pdf-upload-url returned an.



# Create compliance policy | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/create-compliance-policy

/openapi.json post /v1/policies
Create a policy record that can be reviewed, versioned, published, linked to controls, and used as source evidence for questionnaires.



# Create policy version | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/create-policy-version

/openapi.json post /v1/policies/{id}/versions
Creates a new draft version of a policy, cloned from the policy's newest version — an unpublished draft included, a version awaiting approval skipped.



# Decline the framework template updates for | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/decline-the-framework-template-updates-for-one-policy

/openapi.json post /v1/policy-template-updates/{id}/decline
Stops offering this update to everyone in the organization. PERMANENT never offers it again; UNTIL_TEMPLATE_CHANGES offers it again once the template’s.



# Delete a policy version PDF | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/delete-a-policy-version-pdf

/openapi.json delete /v1/policies/{id}/pdf
Deletes the PDF from a specific policy version. If no versionId is provided, deletes from the latest draft version. Cannot delete PDFs from published.



# Delete compliance policy | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/delete-compliance-policy

/openapi.json delete /v1/policies/{id}
Delete a compliance policy that is no longer part of the organization evidence library or control program.



# Delete policy version | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/delete-policy-version

/openapi.json delete /v1/policies/{id}/versions/{versionId}
Delete policy version in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting and approval workflows.



# Deny pending policy changes | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/deny-pending-policy-changes

/openapi.json post /v1/policies/{id}/deny-changes
Deny pending policy changes in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting and approval.



# Download all published policies | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/download-all-published-policies

/openapi.json get /v1/policies/download-all
Generate a single PDF bundle of published compliance policies for auditors, customer security reviews, and Trust Center workflows.



# Get a signed URL for the policy PDF | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/get-a-signed-url-for-the-policy-pdf

/openapi.json get /v1/policies/{id}/pdf/signed-url
Get a signed URL for the policy PDF in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting.



# Get compliance policy | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/get-compliance-policy

/openapi.json get /v1/policies/{id}
Retrieve a single compliance policy by its ID, including current content, draft content, review status, framework links, and audit metadata. Use this.



# Get mapped and all controls for a policy | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/get-mapped-and-all-controls-for-a-policy

/openapi.json get /v1/policies/{id}/controls
Get mapped and all controls for a policy in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting.



# Get policy version by ID | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/get-policy-version-by-id

/openapi.json get /v1/policies/{id}/versions/{versionId}
Get policy version by ID in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting and approval workflows.



# Get policy versions | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/get-policy-versions

/openapi.json get /v1/policies/{id}/versions
Get policy versions in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting and approval workflows.



# Get signed URL for policy PDF (alternate path) | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/get-signed-url-for-policy-pdf-alternate-path

/openapi.json get /v1/policies/{id}/pdf-url
Get signed URL for policy PDF (alternate path) in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting.



# Get tasks that serve as evidence for a | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/get-tasks-that-serve-as-evidence-for-a-policy-grouped-by-control

/openapi.json get /v1/policies/{id}/evidence-tasks
Get tasks that serve as evidence for a policy, grouped by control in Comp AI. Create, version, publish, export, map, and improve compliance policies.



# Link references from a document to other | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/link-references-from-a-document-to-other-documents

/openapi.json post /v1/policies/{id}/references
Adds references from a policy, standard or procedure to other documents in the same organization, e.g. the policies a standard implements. Idempotent. Read.



# List compliance policies | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/list-compliance-policies

/openapi.json get /v1/policies
Lists an organization's active compliance policies by default, covering the whole library that evidences frameworks such as SOC 2, ISO 27001, and GDPR.



# List policies with framework template updates | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/list-policies-with-framework-template-updates-available

/openapi.json get /v1/policy-template-updates
Blocks added to a policy template since the policy was generated, per policy. A policy whose update the organization declined is left out. Nothing is changed.



# List policy acknowledgments | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/list-policy-acknowledgments

/openapi.json get /v1/policy-acknowledgments
Returns one row per member per required policy, with the acknowledgment date when recorded. Use for audit evidence of who accepted which policy and when. A.



# Map controls to a policy | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/map-controls-to-a-policy

/openapi.json post /v1/policies/{id}/controls
Map controls to a policy in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting and approval workflows.



# Preview the framework template updates for | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/preview-the-framework-template-updates-for-one-policy

/openapi.json get /v1/policy-template-updates/{id}
Preview the framework template updates for one policy in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted.



# Publish all draft policies | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/publish-all-draft-policies

/openapi.json post /v1/policies/publish-all
Publish draft policies in bulk so approved policy content can power Trust Center sharing, questionnaire answers, and audit evidence.



# Publish policy version | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/publish-policy-version

/openapi.json post /v1/policies/{id}/versions/publish
Publishes a draft policy version, making it the active/current version of the policy. Pass the versionId of the draft you want to publish — for example one.



# Re-read an attached policy document into the | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/re-read-an-attached-policy-document-into-the-editor

/openapi.json post /v1/policies/{id}/extract-document
Queues a fresh read of the PDF already attached to a policy, storing its text as the version's editor content. Use when an uploaded policy still reads as.



# Regenerate policy with AI | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/regenerate-policy-with-ai

/openapi.json post /v1/policies/{id}/regenerate
Regenerate policy content using Comp AI while keeping the result reviewable before it is published or used as compliance evidence.



# Remove a control mapping from a policy | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/remove-a-control-mapping-from-a-policy

/openapi.json delete /v1/policies/{id}/controls/{controlId}
Remove a control mapping from a policy in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting.



# Remove a document reference | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/remove-a-document-reference

/openapi.json delete /v1/policies/{id}/references/{targetId}
Removes one reference a document (policy, standard or procedure) holds to another document. Read current references via GET /v1/policies/{id}. Idempotent —.



# Request a presigned URL to upload a policy PDF | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/request-a-presigned-url-to-upload-a-policy-pdf

/openapi.json post /v1/policies/{id}/pdf/upload-url
Generates a presigned S3 URL for uploading a policy PDF directly to storage. Use this when attaching a PDF to a compliance policy — the file bytes are.



# Set active policy version | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/set-active-policy-version

/openapi.json post /v1/policies/{id}/versions/{versionId}/activate
Set active policy version in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting and approval workflows.



# Submit version for approval | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/submit-version-for-approval

/openapi.json post /v1/policies/{id}/versions/{versionId}/submit-for-approval
Submit version for approval in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting and approval.



# Summarize policy acknowledgments by member | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/summarize-policy-acknowledgments-by-member

/openapi.json get /v1/policy-acknowledgments/summary
Returns one row per active member with the date of their most recent policy acceptance across all required policies. Use for a people overview; call the.



# Update compliance policy | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/update-compliance-policy

/openapi.json patch /v1/policies/{id}
Update compliance policy details or content while keeping policy workflows connected to controls, tasks, and approvals.



# Update version content | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/update-version-content

/openapi.json patch /v1/policies/{id}/versions/{versionId}
Update version content in Comp AI. Create, version, publish, export, map, and improve compliance policies with AI-assisted drafting and approval workflows.



# Upload a PDF to a policy version (UI-only) | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/policies/upload-a-pdf-to-a-policy-version-ui-only

/openapi.json post /v1/policies/{id}/pdf
Uploads a PDF via multipart `file` or base64 `fileData` JSON. Defaults to the latest draft if no `versionId`; 400 if no draft is available. UI-only — AI.



# Answer one questionnaire question | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/answer-a-single-questionnaire-question

/openapi.json post /v1/questionnaire/answer-single
Generate an answer for one security questionnaire item using the organization evidence library and return source references for review.



# Stream generated questionnaire answers | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/auto-answer-a-questionnaire

/openapi.json post /v1/questionnaire/auto-answer
Stream generated questionnaire answers over server-sent events so clients can show progress while answers are produced.



# Delete a security questionnaire | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/delete-a-questionnaire

/openapi.json delete /v1/questionnaire/{id}
Delete a saved security questionnaire when a customer review or vendor assessment no longer needs to be retained.



# Delete questionnaire answer | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/delete-a-questionnaire-answer

/openapi.json post /v1/questionnaire/delete-answer
Delete a stored questionnaire answer when it should be removed from the active response set.



# Export a security questionnaire | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/export-a-questionnaire

/openapi.json post /v1/questionnaire/export
Export a saved security questionnaire response package as PDF, CSV, or XLSX for customer and vendor security reviews.



# Export generated questionnaire answers | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/export-questionnaire-answers

/openapi.json post /v1/questionnaire/answers/export
Generate and export questionnaire answers from a submitted payload using approved organization evidence.



# Generate answers for a questionnaire | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/generate-answers-for-a-questionnaire

/openapi.json post /v1/questionnaire/{id}/auto-answer
Starts background answer generation for an already-parsed questionnaire and returns a run handle immediately. Poll GET /v1/questionnaire/:id until.



# Get security questionnaire details | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/get-a-questionnaire-by-id

/openapi.json get /v1/questionnaire/{id}
Retrieve one saved security questionnaire, including extracted questions, generated answers, and review context for the requesting client.



# List security questionnaires | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/list-questionnaires

/openapi.json get /v1/questionnaire
List saved security questionnaires for an organization so teams can track customer reviews, answer status, and response history.



# Parse questionnaire content | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/parse-an-uploaded-questionnaire-file

/openapi.json post /v1/questionnaire/parse
Parse questionnaire content from a submitted payload so teams can extract security questions before generating or reviewing answers.



# Save questionnaire answer | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/save-a-questionnaire-answer

/openapi.json post /v1/questionnaire/save-answer
Save a manual or AI-generated security questionnaire answer for later review, export, and audit tracking.



# Auto-answer uploaded questionnaire | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/upload-a-questionnaire-file-and-auto-answer-with-export

/openapi.json post /v1/questionnaire/parse/upload
Upload a questionnaire file and generate answer exports from approved organization evidence in PDF, CSV, or XLSX format.



# Upload and export generated answers | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/upload-a-questionnaire-file-and-export-auto-generated-answers

/openapi.json post /v1/questionnaire/answers/export/upload
Upload a questionnaire file and return generated answer exports in PDF, CSV, or XLSX format.



# Upload and parse questionnaire file | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/upload-a-questionnaire-file-and-parse-its-questions

/openapi.json post /v1/questionnaire/upload-and-parse/upload
Upload a security questionnaire file, extract questions, save the parsed questionnaire, and return its identifier and question count.



# Start questionnaire parsing | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/questionnaire/upload-and-parse-a-questionnaire-file

/openapi.json post /v1/questionnaire/upload-and-parse
Upload a questionnaire payload and start asynchronous parsing, returning a run ID for real-time progress tracking.



# Dismiss an evidence review issue | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/review-issues/dismiss-an-evidence-review-issue

/openapi.json post /v1/review-issues/{id}/dismiss
Dismisses an open evidence review issue with a reason, for example when it does not apply. Comp AI CX can see the reason. The issue stays dismissed until.



# List evidence review issues | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/review-issues/list-evidence-review-issues

/openapi.json get /v1/review-issues
Lists advisory issues found by automatic evidence review, such as tasks that do not fit the company context, with why an auditor would object and how to fix.



# Create organization risk | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/risks/create-organization-risk

/openapi.json post /v1/risks
Create a risk record with ownership and context so compliance teams can track mitigation and remediation work.



# Delete organization risk | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/risks/delete-organization-risk

/openapi.json delete /v1/risks/{id}
Delete an organization risk that no longer needs active tracking in the risk register or compliance program.



# Get organization risk | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/risks/get-organization-risk

/openapi.json get /v1/risks/{id}
Retrieve one organization risk with owner, department, likelihood, impact, mitigation, and remediation context.



# Get risk counts grouped by department | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/risks/get-risk-counts-grouped-by-department

/openapi.json get /v1/risks/stats/by-department
Get risk counts grouped by department in Comp AI. Create, update, and report on organizational risks with ownership, departments, and compliance remediation.



# Get risk statistics grouped by assignee | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/risks/get-risk-statistics-grouped-by-assignee

/openapi.json get /v1/risks/stats/by-assignee
Get risk statistics grouped by assignee in Comp AI. Create, update, and report on organizational risks with ownership, departments, and compliance.



# List organization risks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/risks/list-organization-risks

/openapi.json get /v1/risks
List organization risks with owners, departments, severity, mitigation status, and evidence for risk management reporting.



# List risk-owner acceptance events | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/risks/list-risk-owner-acceptance-events

/openapi.json get /v1/risks/{id}/acceptances
Returns the residual-risk acceptance history for a risk, newest first. Each event freezes the residual rating at acceptance and carries a stale flag set.



# Record risk-owner acceptance | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/risks/record-risk-owner-acceptance

/openapi.json post /v1/risks/{id}/acceptances
Records an immutable, timestamped acceptance of a risk's current residual risk by the risk owner (or a chosen member). Re-record after the residual rating.



# Update organization risk | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/risks/update-organization-risk

/openapi.json patch /v1/risks/{id}
Update a risk record as mitigation work progresses so compliance reports reflect the current risk posture.



# Create a custom role | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/roles/create-a-custom-role

/openapi.json post /v1/roles
Create a custom role in Comp AI. Create custom roles and resolve permission sets for organization-level access control.



# Delete a custom role | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/roles/delete-a-custom-role

/openapi.json delete /v1/roles/{roleId}
Delete a custom role in Comp AI. Create custom roles and resolve permission sets for organization-level access control.



# Get a role by ID | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/roles/get-a-role-by-id

/openapi.json get /v1/roles/{roleId}
Get a role by ID in Comp AI. Create custom roles and resolve permission sets for organization-level access control.



# Get obligations for a built-in role | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/roles/get-obligations-for-a-built-in-role

/openapi.json get /v1/roles/built-in/{name}/obligations
Returns the effective obligations for a built-in role (owner, admin, auditor, employee, contractor) — DB override if present, else the hardcoded default.



# List all roles | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/roles/list-all-roles

/openapi.json get /v1/roles
List all roles in Comp AI. Create custom roles and resolve permission sets for organization-level access control.



# Resolve permissions for custom roles | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/roles/resolve-permissions-for-custom-roles

/openapi.json get /v1/roles/permissions
Returns the merged permissions for the given custom role names. Used by the frontend to resolve effective permissions for users with custom roles.



# Update a custom role | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/roles/update-a-custom-role

/openapi.json patch /v1/roles/{roleId}
Update a custom role in Comp AI. Create custom roles and resolve permission sets for organization-level access control.



# Update obligations for a built-in role | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/roles/update-obligations-for-a-built-in-role

/openapi.json patch /v1/roles/built-in/{name}/obligations
Override the obligations for a built-in role (e.g., turn off the compliance obligation for owners). Permissions stay sourced from the hardcoded defaults.



# Search compliance records | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/search/search-compliance-records

/openapi.json get /v1/search
Search policies, tasks, documents, people, controls, vendors, and risks by keyword in one call to locate a compliance record before fetching it by ID.



# Add context to a pentest finding | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/add-context-to-a-pentest-finding

/openapi.json put /v1/pentest-finding-contexts/{issueId}
Saves a customer context note on a pentest finding, e.g. an accepted-by-design rationale or remediation details. Future scans of the same target pass the.



# Create penetration test | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/create-penetration-test

/openapi.json post /v1/security-penetration-tests
Create an AI-powered penetration test run for an approved target and track the resulting findings and report artifacts.



# Get penetration test agent events | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/get-penetration-test-agent-events

/openapi.json get /v1/security-penetration-tests/{id}/events
Get penetration test agent events in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown.



# Get penetration test issues | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/get-penetration-test-issues

/openapi.json get /v1/security-penetration-tests/{id}/issues
Returns structured findings from the run. Streaming providers add issues during a scan; other providers publish findings on completion.



# Get penetration test output | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/get-penetration-test-output

/openapi.json get /v1/security-penetration-tests/{id}/report
Get penetration test output in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.



# Get penetration test PDF | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/get-penetration-test-pdf

/openapi.json get /v1/security-penetration-tests/{id}/pdf
Get penetration test PDF in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.



# Get penetration test progress | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/get-penetration-test-progress

/openapi.json get /v1/security-penetration-tests/{id}/progress
Returns progress for a run, including reconcileHealth (ok, retrying, stalled) so clients can tell an interrupted scan from a live one.



# Get penetration test status | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/get-penetration-test-status

/openapi.json get /v1/security-penetration-tests/{id}
Get penetration test status in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.



# List penetration test runs | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/list-penetration-test-runs

/openapi.json get /v1/security-penetration-tests
List penetration test runs in Comp AI. Create AI-powered penetration test runs, track progress, inspect findings and events, and download markdown or PDF.



# List pentest finding context notes | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/list-pentest-finding-context-notes

/openapi.json get /v1/pentest-finding-contexts
Returns the customer-written context notes attached to pentest findings for a target URL. These notes are shared with the testing agent on future scans of.



# Remove context from a pentest finding | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/remove-context-from-a-pentest-finding

/openapi.json delete /v1/pentest-finding-contexts/{issueId}
Deletes the customer context note attached to a pentest finding so future scans of the target no longer receive it from the testing agent briefing.



# Update a penetration test finding status | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/security-penetration-tests/update-a-penetration-test-finding-status

/openapi.json patch /v1/security-penetration-tests/{id}/issues/{issueId}
Triage or dispute a single penetration test finding. Marking one `false_positive` or `wont_fix` requires a justification note, recorded in the finding's.



# Approve a SOA document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/soa/approve-a-soa-document

/openapi.json post /v1/soa/approve
Approve a SOA document in Comp AI. Create, auto-fill, review, approve, and export ISO 27001 Statement of Applicability documents.



# Auto-fill ISO 27001 SOA | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/soa/auto-fill-iso-27001-soa

/openapi.json post /v1/soa/auto-fill
Auto-fill a Statement of Applicability draft using organization context and framework mappings for ISO 27001 review.



# Create a new SOA document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/soa/create-a-new-soa-document

/openapi.json post /v1/soa/create-document
Create a new SOA document in Comp AI. Create, auto-fill, review, approve, and export ISO 27001 Statement of Applicability documents.



# Decline a SOA document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/soa/decline-a-soa-document

/openapi.json post /v1/soa/decline
Decline a SOA document in Comp AI. Create, auto-fill, review, approve, and export ISO 27001 Statement of Applicability documents.



# Ensure SOA configuration and document exist | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/soa/ensure-soa-configuration-and-document-exist

/openapi.json post /v1/soa/ensure-setup
Ensure SOA configuration and document exist in Comp AI. Create, auto-fill, review, approve, and export ISO 27001 Statement of Applicability documents.



# Export ISO 27001 SOA | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/soa/export-iso-27001-soa

/openapi.json post /v1/soa/export
Export the approved Statement of Applicability document for ISO 27001 auditors, customer reviews, and internal records.



# Read SOA configuration and document without | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/soa/read-soa-configuration-and-document-without-creating-either

/openapi.json post /v1/soa/get-setup
Read SOA configuration and document without creating either in Comp AI. Create, auto-fill, review, approve, and export ISO 27001 Statement of Applicability.



# Save a SOA answer | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/soa/save-a-soa-answer

/openapi.json post /v1/soa/save-answer
Save a SOA answer in Comp AI. Create, auto-fill, review, approve, and export ISO 27001 Statement of Applicability documents.



# Submit SOA document for approval | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/soa/submit-soa-document-for-approval

/openapi.json post /v1/soa/submit-for-approval
Submit SOA document for approval in Comp AI. Create, auto-fill, review, approve, and export ISO 27001 Statement of Applicability documents.



# Count automation runs since a date | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/count-automation-runs-since-a-date

/openapi.json get /v1/tasks/{taskId}/automations/{automationId}/runs/summary
Count all runs of one automation created since a timestamp, and how many succeeded. Use for success-rate metrics instead of listing runs.



# Create a published version record for an | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/create-a-published-version-record-for-an-automation

/openapi.json post /v1/tasks/{taskId}/automations/{automationId}/versions
Create a published version record for an automation in Comp AI. Create, version, run, and inspect automated evidence collection workflows attached.



# Create evidence automation | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/create-evidence-automation

/openapi.json post /v1/tasks/{taskId}/automations
Create an automated evidence workflow attached to a task so Comp AI can collect recurring proof from connected systems.



# Delete an automation | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/delete-an-automation

/openapi.json delete /v1/tasks/{taskId}/automations/{automationId}
Delete an automation in Comp AI. Create, version, run, and inspect automated evidence collection workflows attached to compliance tasks.



# Download an automation version script | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/download-an-automation-version-script

/openapi.json get /v1/tasks/{taskId}/automations/{automationId}/versions/{version}/script
Downloads the exact script a published automation version ran, as a plain-text attachment. Evidence artifacts name the version that produced them, so this.



# Get all automations for a task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/get-all-automations-for-a-task

/openapi.json get /v1/tasks/{taskId}/automations
Get all automations for a task in Comp AI. Create, version, run, and inspect automated evidence collection workflows attached to compliance tasks.



# Get all versions for an automation | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/get-all-versions-for-an-automation

/openapi.json get /v1/tasks/{taskId}/automations/{automationId}/versions
Get all versions for an automation in Comp AI. Create, version, run, and inspect automated evidence collection workflows attached to compliance tasks.



# Get automation details | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/get-automation-details

/openapi.json get /v1/tasks/{taskId}/automations/{automationId}
Get automation details in Comp AI. Create, version, run, and inspect automated evidence collection workflows attached to compliance tasks.



# Get recent automation runs for a task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/get-recent-automation-runs-for-a-task

/openapi.json get /v1/tasks/{taskId}/automations/runs
Retrieve the newest evidence automation runs across all automations of a task, newest first. Use limit to choose how many (default 50, max 100).



# Get recent runs for a specific automation | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/get-recent-runs-for-a-specific-automation

/openapi.json get /v1/tasks/{taskId}/automations/{automationId}/runs
Retrieve the newest runs of one automation, newest first, with logs and output. Use limit to choose how many (default 50, max 100).



# Update an existing automation | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-automations/update-an-existing-automation

/openapi.json patch /v1/tasks/{taskId}/automations/{automationId}
Update an existing automation in Comp AI. Create, version, run, and inspect automated evidence collection workflows attached to compliance tasks.



# Create a new task item | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-management/create-a-new-task-item

/openapi.json post /v1/task-management
Create a new task item in Comp AI. Manage task items and attachments linked to operational entities such as risks and vendors.



# Delete a task item | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-management/delete-a-task-item

/openapi.json delete /v1/task-management/{id}
Delete a task item in Comp AI. Manage task items and attachments linked to operational entities such as risks and vendors.



# Delete attachment from task item | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-management/delete-attachment-from-task-item

/openapi.json delete /v1/task-management/attachments/{attachmentId}
Delete attachment from task item in Comp AI. Manage task items and attachments linked to operational entities such as risks and vendors.



# Get task item activity log | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-management/get-task-item-activity-log

/openapi.json get /v1/task-management/{id}/activity
Get task item activity log in Comp AI. Manage task items and attachments linked to operational entities such as risks and vendors.



# Get task items for an entity | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-management/get-task-items-for-an-entity

/openapi.json get /v1/task-management
Get task items for an entity in Comp AI. Manage task items and attachments linked to operational entities such as risks and vendors.



# Get task items statistics for an entity | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-management/get-task-items-statistics-for-an-entity

/openapi.json get /v1/task-management/stats
Get task items statistics for an entity in Comp AI. Manage task items and attachments linked to operational entities such as risks and vendors.



# Update a task item | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-management/update-a-task-item

/openapi.json put /v1/task-management/{id}
Update a task item in Comp AI. Manage task items and attachments linked to operational entities such as risks and vendors.



# Upload attachment to task item | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/task-management/upload-attachment-to-task-item

/openapi.json post /v1/task-management/attachments
Upload a file attachment for a task item with proper S3 path structure: org_{orgId}/attachments/task-item/{entityType}/{entityId}/files.



# Approve a task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/approve-a-task

/openapi.json post /v1/tasks/{taskId}/approve
Approve a task that is in review. Only the assigned approver can approve. Moves status to done and creates an audit comment.



# Bulk submit tasks for review | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/bulk-submit-tasks-for-review

/openapi.json post /v1/tasks/bulk/submit-for-review
Bulk submit tasks for review in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity.



# Create compliance task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/create-compliance-task

/openapi.json post /v1/tasks
Create a compliance task for evidence collection, remediation, review, or recurring control work inside an organization.



# Delete a task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/delete-a-task

/openapi.json delete /v1/tasks/{taskId}
Delete a task in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity history.



# Delete multiple tasks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/delete-multiple-tasks

/openapi.json delete /v1/tasks/bulk
Delete multiple tasks in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity history.



# Delete task attachment | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/delete-task-attachment

/openapi.json delete /v1/tasks/{taskId}/attachments/{attachmentId}
Delete task attachment in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity history.



# Get page options for tasks overview | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/get-page-options-for-tasks-overview

/openapi.json get /v1/tasks/options
Get page options for tasks overview in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links.



# Get policies that reference a task via shared | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/get-policies-that-reference-a-task-via-shared-controls

/openapi.json get /v1/tasks/{taskId}/policies
Get policies that reference a task via shared controls in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy.



# Get task activity | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/get-task-activity

/openapi.json get /v1/tasks/{taskId}/activity
Get task activity in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity history.



# Get task attachment download URL | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/get-task-attachment-download-url

/openapi.json get /v1/tasks/{taskId}/attachments/{attachmentId}/download
Generate a signed download URL for an attachment on a compliance task so reviewers can access uploaded evidence.



# Get task attachments | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/get-task-attachments

/openapi.json get /v1/tasks/{taskId}/attachments
Get task attachments in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity history.



# Get task by ID | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/get-task-by-id

/openapi.json get /v1/tasks/{taskId}
Get task by ID in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity history.



# Get task templates | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/get-task-templates

/openapi.json get /v1/tasks/templates
Lists task templates, optionally by framework. Copies sharing a name (ignoring case and surrounding spaces) are returned once, as the earliest-created copy.



# List compliance tasks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/list-compliance-tasks

/openapi.json get /v1/tasks
List compliance tasks with assignments and status so teams can track audit readiness, evidence work, and control implementation.



# Preview a task attachment inline | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/preview-a-task-attachment-inline

/openapi.json get /v1/tasks/{taskId}/attachments/{attachmentId}/preview
Returns a task attachment in a form the browser can display: an inline signed URL for PDFs, images and text files, or HTML converted from Word and Excel.



# Regenerate task from template | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/regenerate-task-from-template

/openapi.json post /v1/tasks/{taskId}/regenerate
Regenerate task from template in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity.



# Reject a task review | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/reject-a-task-review

/openapi.json post /v1/tasks/{taskId}/reject
Reject a task that is in review. Only the assigned approver can reject. Reverts status to the previous status and creates an audit comment.



# Reorder tasks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/reorder-tasks

/openapi.json patch /v1/tasks/reorder
Reorder tasks in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity history.



# Submit task for review | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/submit-task-for-review

/openapi.json post /v1/tasks/{taskId}/submit-for-review
Submit task for review in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity history.



# Update a task | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/update-a-task

/openapi.json patch /v1/tasks/{taskId}
Update a task in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity history.



# Update assignee for multiple tasks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/update-assignee-for-multiple-tasks

/openapi.json patch /v1/tasks/bulk/assignee
Update assignee for multiple tasks in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity.



# Update status for multiple tasks | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/update-status-for-multiple-tasks

/openapi.json patch /v1/tasks/bulk
Update status for multiple tasks in Comp AI. Manage compliance task lifecycle, assignments, review approvals, evidence uploads, policy links, and activity.



# Upload task evidence | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/tasks/upload-task-evidence

/openapi.json post /v1/tasks/{taskId}/attachments
Upload an evidence attachment to a task so auditors and reviewers can trace completion back to source documentation.



# Get a single timeline instance with phases | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/timelines/get-a-single-timeline-instance-with-phases

/openapi.json get /v1/timelines/{id}
Get a single timeline instance with phases in Comp AI. Track audit and compliance readiness timelines, phases, and review milestones for an organization.



# List timelines for the organization | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/timelines/list-timelines-for-the-organization

/openapi.json get /v1/timelines
List timelines for the organization in Comp AI. Track audit and compliance readiness timelines, phases, and review milestones for an organization.



# Mark a phase as ready for review | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/timelines/mark-a-phase-as-ready-for-review

/openapi.json post /v1/timelines/{id}/phases/{phaseId}/ready
Mark a phase as ready for review in Comp AI. Track audit and compliance readiness timelines, phases, and review milestones for an organization.



# Generate HIPAA training certificate PDF | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/training/generate-hipaa-training-certificate-pdf

/openapi.json post /v1/training/generate-hipaa-certificate
Generate HIPAA training certificate PDF in Comp AI. Record security awareness and HIPAA training completion status and generate completion certificates.



# Generate training certificate | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/training/generate-training-certificate

/openapi.json post /v1/training/generate-certificate
Generate a training completion certificate that can be shared with auditors or attached as workforce security evidence.



# Get my training video completions | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/training/get-my-training-video-completions

/openapi.json get /v1/training/completions/me
Returns the training video completion records of the authenticated member. Needs a caller that carries a member (a session or an MCP OAuth connection); an.



# List training completions | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/training/list-training-completions

/openapi.json get /v1/training/completions
List security awareness and HIPAA training completion records for workforce compliance tracking and audit evidence.



# Mark a training video as complete | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/training/mark-a-training-video-as-complete

/openapi.json post /v1/training/completions/{videoId}/complete
Marks a specific training video as completed for the authenticated member. Triggers completion email if all training is now done.



# Send HIPAA training completion email with | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/training/send-hipaa-training-completion-email-with-certificate

/openapi.json post /v1/training/send-hipaa-completion-email
Checks if the member has completed the HIPAA Security Awareness Training. If so, sends an email with the HIPAA training certificate attached.



# Send training completion email with | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/training/send-training-completion-email-with-certificate

/openapi.json post /v1/training/send-completion-email
Send training completion email with certificate in Comp AI. Record security awareness and HIPAA training completion status and generate completion.



# Approve Trust Access request | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/approve-trust-access-request

/openapi.json post /v1/trust-access/admin/requests/{id}/approve
Approve a Trust Center access request, configure the grant window, and start the NDA or access email workflow.



# Deny Trust Access request | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/deny-trust-access-request

/openapi.json post /v1/trust-access/admin/requests/{id}/deny
Reject a Trust Center access request with a review reason so customer security access decisions stay auditable.



# Get controls shown on a trust portal | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/get-controls-shown-on-a-trust-portal

/openapi.json get /v1/trust-access/{friendlyUrl}/controls
Public list of the security controls visible on a published trust portal. Controls the organization toggled off — or whose template default hides them — are.



# Get org-authored custom frameworks shown on a | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/get-org-authored-custom-frameworks-shown-on-a-trust-portal

/openapi.json get /v1/trust-access/{friendlyUrl}/custom-frameworks
Get org-authored custom frameworks shown on a trust portal in Comp AI. Manage external Trust Center access requests, NDA signing, grants, tokenized document.



# Get Security Questionnaire visibility for a | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/get-security-questionnaire-visibility-for-a-trust-portal

/openapi.json get /v1/trust-access/{friendlyUrl}/security-questionnaire
Whether the org offers the AI-assisted Security Questionnaire on its public trust portal. Defaults to enabled when the portal can't be resolved.



# Get Trust Access request | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/get-trust-access-request

/openapi.json get /v1/trust-access/admin/requests/{id}
Retrieve one Trust Center access request with requester context, status, review metadata, and audit details.



# Get Trust Center FAQs | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/get-trust-center-faqs

/openapi.json get /v1/trust-access/{friendlyUrl}/faqs
Retrieve published Trust Center FAQs for an organization so public trust pages can show customer security answers.



# Get Trust Center favicon | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/get-trust-center-favicon

/openapi.json get /v1/trust-access/{friendlyUrl}/favicon
Retrieve the favicon URL used by a published Trust Center so embedded or mirrored experiences can match branding.



# Get Trust Center overview | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/get-trust-center-overview

/openapi.json get /v1/trust-access/{friendlyUrl}/overview
Retrieve the published Trust Center overview for an organization, including public security posture messaging.



# List Trust Access grants | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/list-trust-access-grants

/openapi.json get /v1/trust-access/admin/grants
List active, expired, and revoked Trust Access grants for customer security reviews and shared compliance resources.



# List Trust Access requests | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/list-trust-access-requests

/openapi.json get /v1/trust-access/admin/requests
List pending and completed Trust Center access requests so teams can review customer security inquiries through the API.



# List Trust Center custom links | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/list-trust-center-custom-links

/openapi.json get /v1/trust-access/{friendlyUrl}/custom-links
List published custom links shown on an organization Trust Center for customer security and compliance reviews.



# List Trust Center vendors | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/list-trust-center-vendors

/openapi.json get /v1/trust-access/{friendlyUrl}/vendors
List published vendors and subprocessors for an organization Trust Center so reviewers can inspect third-party posture.



# Preview or download the Trust Access NDA | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/preview-or-download-the-trust-access-nda

/openapi.json post /v1/trust-access/admin/requests/{id}/preview-nda
Return the executed NDA PDF for a Trust Access request once the reviewer has signed, or generate a preview copy of the agreement before signing.



# Reclaim Trust Access link | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/reclaim-trust-access-link

/openapi.json post /v1/trust-access/{friendlyUrl}/reclaim
Request a fresh Trust Access link for a reviewer who already has an active grant on a published Trust Center.



# Resend Trust Access email | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/resend-trust-access-email

/openapi.json post /v1/trust-access/admin/grants/{id}/resend-access-email
Resend the access email for an active Trust Access grant so approved reviewers can reopen shared resources.



# Resend Trust Access NDA | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/resend-trust-access-nda

/openapi.json post /v1/trust-access/admin/requests/{id}/resend-nda
Resend an NDA signing email for a Trust Access request that still requires reviewer signature.



# Revoke Trust Access grant | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/revoke-trust-access-grant

/openapi.json post /v1/trust-access/admin/grants/{id}/revoke
Immediately revoke a Trust Access grant when a customer review ends or shared compliance access should be removed.



# Submit Trust Access request | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-access/submit-trust-access-request

/openapi.json post /v1/trust-access/{friendlyUrl}/requests
Submit a Trust Center access request with requester details, company context, and review reason for administrator approval.



# Add or update a custom domain for the trust | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/add-or-update-a-custom-domain-for-the-trust-portal

/openapi.json post /v1/trust-portal/settings/custom-domain
Add or update a custom domain for the trust portal in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources.



# Check DNS records for a custom domain | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/check-dns-records-for-a-custom-domain

/openapi.json post /v1/trust-portal/settings/check-dns
Check DNS records for a custom domain in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents.



# Create a custom link for trust portal | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/create-a-custom-link-for-trust-portal

/openapi.json post /v1/trust-portal/custom-links
Create a custom link for trust portal in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents.



# Delete a custom link | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/delete-a-custom-link

/openapi.json post /v1/trust-portal/custom-links/{linkId}/delete
Delete a custom link in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents, links, and vendor.



# Delete (deactivate) a trust portal document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/delete-deactivate-a-trust-portal-document

/openapi.json post /v1/trust-portal/documents/{documentId}/delete
Delete (deactivate) a trust portal document in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources.



# Enable or disable the trust portal | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/enable-or-disable-the-trust-portal

/openapi.json put /v1/trust-portal/settings/toggle
Enable or disable the trust portal in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents.



# Enable/disable a custom framework on the | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/enabledisable-a-custom-framework-on-the-trust-portal-and-set-its-status

/openapi.json put /v1/trust-portal/custom-frameworks
Enable/disable a custom framework on the trust portal and set its status in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs.



# Generate a temporary signed URL for a | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/generate-a-temporary-signed-url-for-a-compliance-certificate

/openapi.json post /v1/trust-portal/compliance-resources/signed-url
Generate a temporary signed URL for a compliance certificate in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance.



# Generate a temporary signed URL for a trust | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/generate-a-temporary-signed-url-for-a-trust-portal-document

/openapi.json post /v1/trust-portal/documents/{documentId}/download
Generate a temporary signed URL for a trust portal document in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance.



# Get domain verification status | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/get-domain-verification-status

/openapi.json get /v1/trust-portal/domain/status
Get domain verification status in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents, links.



# Get Trust Center settings | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/get-trust-center-settings

/openapi.json get /v1/trust-portal/settings
Retrieve Trust Center settings used to configure public status, custom domains, framework visibility, resources, FAQs, and access rules.



# Get trust portal overview | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/get-trust-portal-overview

/openapi.json get /v1/trust-portal/overview
Get trust portal overview in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents, links.



# List additional trust portal documents for | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/list-additional-trust-portal-documents-for-the-organization

/openapi.json post /v1/trust-portal/documents/list
List additional trust portal documents for the organization in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance.



# List controls with trust portal visibility | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/list-controls-with-trust-portal-visibility

/openapi.json get /v1/trust-portal/controls
Returns the organization's non-archived controls with their trust portal visibility: the effective value, whether it overrides the template default.



# List custom links for trust portal | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/list-custom-links-for-trust-portal

/openapi.json get /v1/trust-portal/custom-links
List custom links for trust portal in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents.



# List org-authored custom frameworks with | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/list-org-authored-custom-frameworks-with-their-trust-portal-selection

/openapi.json get /v1/trust-portal/custom-frameworks
List org-authored custom frameworks with their trust portal selection in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs.



# List uploaded compliance certificates for the | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/list-uploaded-compliance-certificates-for-the-organization

/openapi.json post /v1/trust-portal/compliance-resources/list
List uploaded compliance certificates for the organization in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance.



# List vendors configured for trust portal | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/list-vendors-configured-for-trust-portal

/openapi.json get /v1/trust-portal/vendors
List vendors configured for trust portal in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents.



# Remove a custom framework's Trust Portal | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/remove-a-custom-frameworks-trust-portal-badge-image

/openapi.json delete /v1/trust-portal/custom-frameworks/badge
Remove a custom framework's Trust Portal badge image in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance.



# Remove the trust portal favicon | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/remove-the-trust-portal-favicon

/openapi.json delete /v1/trust-portal/favicon
Remove the trust portal favicon in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents, links.



# Reorder custom links | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/reorder-custom-links

/openapi.json post /v1/trust-portal/custom-links/reorder
Reorder custom links in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents, links, and vendor.



# Show or hide the Security Questionnaire on | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/show-or-hide-the-security-questionnaire-on-the-public-trust-portal

/openapi.json put /v1/trust-portal/settings/security-questionnaire
Show or hide the Security Questionnaire on the public trust portal in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs.



# Update a custom link | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/update-a-custom-link

/openapi.json post /v1/trust-portal/custom-links/{linkId}
Update a custom link in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents, links, and vendor.



# Update allowed domains for the trust portal | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/update-allowed-domains-for-the-trust-portal

/openapi.json put /v1/trust-portal/settings/allowed-domains
Update allowed domains for the trust portal in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources.



# Update allowed emails for the trust portal | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/update-allowed-emails-for-the-trust-portal

/openapi.json put /v1/trust-portal/settings/allowed-emails
Update allowed emails for the trust portal in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources.



# Update control trust portal visibility | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/update-control-trust-portal-visibility

/openapi.json post /v1/trust-portal/controls/{controlId}/trust-settings
Sets whether a control appears on the public trust portal. The choice is stored per organization, overrides the control template default, and is never reset.



# Update Trust Center overview | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/update-trust-center-overview

/openapi.json post /v1/trust-portal/overview
Update the public Trust Center overview content that explains security posture and compliance status to prospects and customers.



# Update trust portal FAQs | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/update-trust-portal-faqs

/openapi.json put /v1/trust-portal/settings/faqs
Update trust portal FAQs in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents, links.



# Update trust portal framework settings | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/update-trust-portal-framework-settings

/openapi.json put /v1/trust-portal/settings/frameworks
Update trust portal framework settings in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents.



# Update vendor trust portal settings | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/update-vendor-trust-portal-settings

/openapi.json post /v1/trust-portal/vendors/{vendorId}/trust-settings
Update vendor trust portal settings in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents.



# Upload a favicon for the trust portal | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/upload-a-favicon-for-the-trust-portal

/openapi.json post /v1/trust-portal/favicon
Upload a favicon for the trust portal in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources, documents.



# Upload an additional trust portal document | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/upload-an-additional-trust-portal-document

/openapi.json post /v1/trust-portal/documents/upload
Upload an additional trust portal document in Comp AI. Configure the live Trust Center, custom domain, public overview, FAQs, compliance resources.



# Upload compliance certificate | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/upload-compliance-certificate

/openapi.json post /v1/trust-portal/compliance-resources/upload
Upload or replace a compliance certificate PDF such as SOC 2, ISO 27001, HIPAA, or GDPR evidence for Trust Center sharing.



# Upload or replace a custom framework's Trust | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/trust-portal/upload-or-replace-a-custom-frameworks-trust-portal-badge-image

/openapi.json post /v1/trust-portal/custom-frameworks/badge
Stores a PNG/JPEG/WebP badge (max 256KB) in the organization assets bucket. Does not change the framework's portal visibility.



# Get a presigned URL to upload a file | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/uploads/get-a-presigned-url-to-upload-a-file

/openapi.json post /v1/uploads/presign
Returns a presigned S3 URL plus the s3Key the file lands at. PUT the raw file bytes to that URL, then call the feature tool (e.g. upload-and-parse) with the.



# Create vendor | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/vendors/create-vendor

/openapi.json post /v1/vendors
Create a vendor record so teams can track third-party risk, assessment evidence, owner, category, and compliance status.



# Delete vendor | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/vendors/delete-vendor

/openapi.json delete /v1/vendors/{id}
Permanently removes a vendor from the organization. This action cannot be undone.



# Get vendor details | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/vendors/get-vendor-details

/openapi.json get /v1/vendors/{id}
Retrieve one vendor record with ownership, review status, risk context, and third-party compliance metadata.



# List vendor risk acceptance events | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/vendors/list-vendor-risk-acceptance-events

/openapi.json get /v1/vendors/{id}/acceptances
Returns the residual-risk acceptance history for a vendor, newest first. Each event freezes the residual rating at acceptance and carries a stale flag set.



# List vendors | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/vendors/list-vendors

/openapi.json get /v1/vendors
List third-party vendors with risk level, owner, assessment status, and Trust Center visibility; filter by name or matches-any dataHandled labels.



# Record vendor risk-owner acceptance | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/vendors/record-vendor-risk-owner-acceptance

/openapi.json post /v1/vendors/{id}/acceptances
Records an immutable, timestamped acceptance of a vendor's current residual risk by the vendor owner (or a chosen member). Re-record after the residual.



# Search global vendors | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/vendors/search-global-vendors

/openapi.json get /v1/vendors/global/search
Search global vendor records to prefill vendor profiles and speed up third-party risk assessment workflows.



# Trigger vendor risk assessment | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/vendors/trigger-vendor-risk-assessment

/openapi.json post /v1/vendors/{id}/trigger-assessment
Trigger a vendor risk assessment so Comp AI can update third-party risk evidence and vendor security review status.



# Update vendor record | Comp AI API
Source: https://www.trycomp.ai/docs/api-reference/vendors/update-vendor-record

/openapi.json patch /v1/vendors/{id}
Update vendor ownership, risk attributes, review metadata, and third-party compliance context for an organization.



# Automated Evidence
Source: https://www.trycomp.ai/docs/automated-evidence

Automate recurring SOC 2, ISO 27001, HIPAA, and GDPR evidence collection from connected systems with Comp AI.

Automated Evidence keeps compliance tasks current by collecting recurring proof from the systems your team already uses. Use it to reduce stale screenshots, manual follow-ups, and last-minute audit evidence work.

### Automated Evidence Demo

[Loom video player](https://www.loom.com/embed/6e80c92e12c4478ab009bc86f7b21f4a)

### Create Automations

To create automations for evidence collection, simply click into any task on the app, and click on the "Create Automation" button.

This will take you to the chat agent, here, you will enter a prompt based on the task and evidence required for that task.

### Example Prompt

In this example, we will use the project ‘Secure Code’ for this task. We need to show that Dependabot (or a similar tool) is enabled and scanning the dependencies in our codebase. For this prompt, we would say:\
“Check if Dependabot is enabled in my GitHub repository and return the results.”

### Testing & Publishing Automations

Once prompted, the agent will run through the process of creating an automation to check for and return any Dependabot alerts, requesting any relevant keys or tokens required by that specific vendor to complete the automation.

Once the automation is complete, click ‘Test’. This will display the first output for that automation. If the output is sufficient, click ‘Publish’. This will publish the automation to the task, which will then run automatically—updating the evidence for that task according to the frequency set.

> [!NOTE]
>
> You can create multiple automations per task. Each piece of evidence will show in the "Automated
> Evidence" card on the task page.


# Browser Automations
Source: https://www.trycomp.ai/docs/browser-automations

Capture audit evidence from vendor websites on a schedule, with optional sign-in and two-factor authentication.

Browser Automations open a vendor's website in a real browser and capture the exact page you need as audit evidence, on a schedule. Sign-in is optional: capture publicly accessible pages without credentials, or connect a login for private pages, including ones protected by two-factor authentication (2FA).

![Automated browser evidence — a captured page with a Comp AI audit banner](https://mintcdn.com/bubbaaiinc/vc5SbvZ_AgLGOWjJ/images/browser-evidence-example.png?fit=max\&auto=format\&n=vc5SbvZ_AgLGOWjJ\&q=85\&s=a0dd9f8e3ad57788d9c01a863b42e1b6)

## Why it's powerful

* **It reaches evidence nothing else can.** Plenty of tools have no API or integration — Browser Automations sign in and screenshot the page directly, so you can prove a control that would otherwise be a manual screenshot.
* **It handles 2FA on its own.** Give it the authenticator setup key once and it generates the codes itself, so scheduled runs never wait on your phone.
* **It stays fresh without you.** When a session expires, it re-signs in on its own — evidence keeps updating on schedule instead of going stale between audits.
* **It's auditor-ready by default.** Every capture is stamped with the requirement, source, and timestamp, and can carry a pass/fail verdict.

This is most useful for **recurring evidence from admin consoles and security-settings pages that have no export or API** — for example, showing that two-factor authentication is enforced, that users have MFA enabled, or that a specific setting is turned on — across as many vendors as you need.

## What you can do

* Collect evidence from web apps that have no API or integration.
* Sign in on a schedule, **including 2FA** — Comp AI generates the one-time code for you.
* Watch a run live and **take over in the browser** if a step needs a human.
* Get an audit-ready screenshot stamped with the source and timestamp, plus an optional pass/fail check.
* Manage every vendor login in one place under **Settings → Browser connections**.

## How it works

There are three parts:

1. **Connections** — the vendor websites and optional logins saved under **Settings → Browser connections**.
2. **Browser evidence** — the automations that use those connections, created inside an evidence task.
3. **Schedule** — Comp AI opens the website, signs in when needed, and captures the page.

> [!NOTE]
>
> You set up an automation inside a task, but the logins it uses are shared across your organization
> — connect a vendor once and any task can use it.

## Prerequisites

Before you start, make sure:

1. Your organization has the feature enabled.
2. You have access to **Settings** and to the evidence task.
3. For private pages, you have the vendor login you want Comp AI to use — ideally a **dedicated service account** rather than a personal one. Public pages need no credentials.

## Connect a vendor

You can connect from a task's **Browser evidence** section, or from **Settings → Browser connections → Connect a vendor**.

1. Enter the **vendor website or page URL**.
2. Comp AI checks the website for available sign-in methods and fields, such as email, username, or workspace.
3. At **Sign in (optional)**, choose a **stored login**, **single sign-on (SSO)**, or **Continue without signing in**. The last option lets the automation use whatever the website makes available without a login.
4. For a **stored login**, enter the username, password, and any required extra fields. For **SSO**, Comp AI opens your identity provider so you can finish signing in there. Comp AI opens a live browser. If a step needs you — a 2FA prompt, an email code — you can **take over in the same browser** and hand it back.

Use **Back** to change the website or sign-in method before completing the connection. You can also continue without signing in while the website check is running.

> [!NOTE]
>
> Credentials are stored **encrypted in a secure vault**. Comp AI keeps only a reference to them —
> never the raw password in plain text.

## Unattended 2FA

This is what makes scheduled runs truly hands-off. If your login uses an authenticator app, give Comp AI the **setup key** once, and it generates the rotating 6-digit codes itself — so scheduled runs never wait on your phone.

![Entering the authenticator setup key, with per-vendor guidance](https://mintcdn.com/bubbaaiinc/vc5SbvZ_AgLGOWjJ/images/browser-2fa-setup-key.png?fit=max\&auto=format\&n=vc5SbvZ_AgLGOWjJ\&q=85\&s=ee806acdbc473346d62327543a20c610)

* **Enter the setup key**, not the code. The setup key is the long, one-time key shown when you add an authenticator app (the "can't scan? enter this code" option) — not the rotating 6-digit code your app displays.
* **Not sure where to find it?** Select **"How do I find this key?"** next to the field. Comp AI shows the steps for your specific vendor, checked against its current help docs.
* You can also turn this on **later** — open the connection under **Settings → Browser connections** and add the authenticator key without re-entering your password.

> [!TIP]
>
> Use a **dedicated authenticator (MFA) device** for the automation — many vendors let you add more
> than one. It's revocable on its own and never touches your personal authenticator.

> [!NOTE]
>
> Comp AI never stores the rotating 6-digit code — only the setup key, encrypted — and generates a
> fresh code at run time.

## Create a browser evidence automation

Inside an evidence task, open the **Browser evidence** section and select **New evidence**. Use a saved connection, or **connect a new vendor** (see [Connect a vendor](#connect-a-vendor)). Sign-in is optional within that connection flow. Saved logins are reused, so a connected vendor needs no new sign-in.

Then:

1. **Describe what to capture** in plain English — for example, *"Open the organization's security settings and show that two-factor authentication is required for all members."*
2. *(Optional)* Add a **pass/fail check** — for example, *"Two-factor authentication is required for everyone."* Without one, the run captures a screenshot only.
3. **Test it.** Watch the automation run live, then review the screenshot and result before you commit.
4. **Save.** It now runs **automatically on the task's schedule** — Daily, Weekly, Monthly, Quarterly, or Yearly, your choice — and keeps the evidence current. You can also run it on demand any time.

![Live test run — the AI controlling a browser to capture evidence](https://mintcdn.com/bubbaaiinc/vc5SbvZ_AgLGOWjJ/images/browser-test-run.png?fit=max\&auto=format\&n=vc5SbvZ_AgLGOWjJ\&q=85\&s=edc26696f5d3c688b9ee222977136ded)

> [!NOTE]
>
> One task can hold several automations — even across different vendors — each producing its own
> screenshot and verdict. Each step of an automation can run on a saved login or as a **public
> page**, so one run can capture a vendor's public policy and its admin settings together.

### Public pages

A step without sign-in opens in a **fresh browser with no saved session** and never tries to sign in,
even if the page shows a "Sign in" button. Choose **Continue without signing in** in the connection
flow to save a reusable **No sign-in** connection. This choice is available even when the website
offers or requires sign-in for other pages. An existing signed-in connection for the same website
stays separate.

You can also choose **No sign-in** in an automation step's connection picker and enter the page URL
without saving a connection. The automation and its screenshots are kept as evidence like any other.

## Schedule and manual runs

Once saved, an automation runs **automatically on a schedule** — you don't have to trigger it. **You choose how often:** set the cadence to **Daily, Weekly, Monthly, Quarterly, or Yearly** from the schedule control in the **Browser evidence** header. One cadence applies to all the browser evidence on that task, so a task's proof refreshes together. You can change it any time.

Need proof right now? **Run** any automation on demand — its screenshot and verdict appear in the row as soon as it finishes, without waiting for the next scheduled run.

On each run — scheduled or manual:

* Comp AI signs in (or, for a public page, opens it directly), navigates to the page you described, and captures a screenshot stamped with the **requirement, source URL, and capture time**. If you added a check, it records a **pass or fail** with a short reason.
* If the saved session has **expired**, Comp AI **re-signs in on its own** — using the stored login and a freshly generated 2FA code. You don't have to do anything.
* If it hits something only a person can clear — a captcha, a "verify it's you" prompt, or an SSO/passkey step — the run pauses and the connection is flagged **Needs reconnect**, with a one-click **Reconnect**.

## Manage your connections

![The Browser connections settings page](https://mintcdn.com/bubbaaiinc/vc5SbvZ_AgLGOWjJ/images/browser-connections.png?fit=max\&auto=format\&n=vc5SbvZ_AgLGOWjJ\&q=85\&s=87a3218aae3a6ecbd1359f1c37fb5a17)

Under **Settings → Browser connections** you can:

* **Connect a vendor** directly, without starting from an evidence task.
* See every connection with its status and sign-in method, including **No sign-in** connections.
* **Search** and page through them when you have many.
* **Reconnect**, **rename**, or **change the login**.
* Turn **Automatic 2FA** on or off, or replace the authenticator key.
* **Remove** a connection you no longer need.

No-sign-in connections need no credentials, two-factor setup, or reconnect. Each run opens a fresh
browser and can access only what the website allows without logging in.

You can also open this page from **Manage connections** in an evidence task's **Browser evidence** section.

## Best practices

1. Use a **dedicated service account** and a **dedicated MFA device** for each automation.
2. Point each automation at the **specific page or setting** so the screenshot shows just that, not a long list.
3. Prefer a **direct sign-in or settings URL** — runs are faster and steadier when they start close to the target.
4. Keep automations meaningful: pair each with a pass/fail check where the requirement is clear.

## Troubleshooting

> **A connection says “Needs reconnect”**
>
> The saved session expired or a login step needs a human
>
> Click **Reconnect**, sign in again, and enter the 2FA code once in the live browser. To avoid this
> every time a session expires, add the **authenticator setup key** so Comp AI can re-sign in on its
> own.

> **The steps for finding my authenticator key look generic**
>
> Vendor-specific vs. general guidance
>
> For well-known vendors, Comp AI shows steps checked against their current help docs. For others it
> shows the universal steps — the exact menu names may differ, so double-check in your account's
> security settings as you go.

> **The run paused for a captcha or “verify it's you”**
>
> Challenges that require a person
>
> Some challenges (captcha, device approval, passkeys) can only be completed by a human. Open the
> connection and **Reconnect** in a live browser to clear it, then future runs continue normally.

> **I don't see Browser connections in Settings**
>
> Feature access and visibility
>
> Your organization may not have the feature enabled, or your user may not have access to Settings.
> Check with an admin.

## Support

If you need help with Browser Automations:

1. Contact support at [support@trycomp.ai](mailto:support@trycomp.ai)
2. Join our [Discord community](https://discord.gg/compai)


# AWS Cloud Tests
Source: https://www.trycomp.ai/docs/cloud-tests/aws

Connect your AWS account with a read-only IAM role to run continuous cloud security checks, and add an optional second role to apply fixes from Comp AI.

## About the AWS integration

Comp AI connects to your AWS account using a **cross-account IAM role** with an **External ID**. No long-lived access keys are created, and all access is scoped to read-only unless you also opt in to auto-remediation with a separate role.

Once connected, Comp AI scans the regions you select and produces findings mapped to common frameworks (SOC 2, ISO 27001, CIS AWS Foundations, PCI DSS, HIPAA).

> [!NOTE]
>
> Comp AI assumes your role from a dedicated AWS principal. You control the trust policy, so you can revoke access at any time by deleting the role.

## How access works

* **Auth model**: AWS STS `AssumeRole` from a Comp AI–managed principal into a role in your account
* **External ID**: Required in the trust policy so only a specific Comp AI organization can assume the role
* **Permissions**: `SecurityAudit` + `ViewOnlyAccess` managed policies, plus two small inline policies for Cost Explorer reads and SSM document metadata
* **Optional auto-remediation**: A separate role (`CompAI-Remediator`) can be created to enable auto-fix actions — this role is **only used when you explicitly trigger a fix**. The audit role stays read-only.

## Prerequisites

Before you begin, make sure you have:

1. An AWS account with permission to create IAM roles
2. Your Comp AI **organization ID** (used as the External ID — Comp AI's connection form pre-fills this for you)
3. Admin access to your Comp AI workspace

## Connect AWS

The Comp AI UI walks you through the full flow and displays the exact CloudShell script to run. The summary below is for reference.

**1. Start the connection in Comp AI**

Go to **Cloud Tests → AWS → Connect**. Comp AI displays a CloudShell script pre-filled with your External ID.

**2. Run the script in AWS CloudShell**

Open [AWS CloudShell](https://console.aws.amazon.com/cloudshell) in the account you want to scan and paste the script. It:

* Creates an IAM role named `CompAI-Auditor`
* Attaches `SecurityAudit` and `ViewOnlyAccess` managed policies
* Adds small inline policies for `ce:GetCostAndUsage` and `ssm:GetDocument` / `ssm:DescribeDocument` / `ssm:ListDocuments`
* Sets a trust policy that only allows Comp AI to assume the role when the correct External ID is supplied
* Prints the new **Role ARN**

**3. Paste the Role ARN and pick regions**

Copy the Role ARN from the script output and paste it into the Comp AI connection form. Choose the regions you want scanned. The External ID is already filled in.

**4. (Optional) Enable auto-remediation**

If you want Comp AI to be able to apply fixes, run the second CloudShell script shown in the UI. It creates a separate `CompAI-Remediator` role with narrower write permissions for the specific services that support auto-fix.

**5. Save and run your first scan**

Click **Save and Connect**. Comp AI validates the role, then queues an initial scan across all selected regions.

## How a fix runs

A fix is always started by a person and carried out by Comp AI. Nothing is changed on a schedule — scans are read-only, and your infrastructure is only modified when someone on your team asks for it.

> [!NOTE]
>
> The **Fix** button only appears once the `CompAI-Remediator` role is saved on the connection. Until then, Cloud Tests can only report — it cannot change anything.

**1. Open a finding and click Fix**

In **Cloud Tests**, findings Comp AI can act on show a **Fix** button. Comp AI assumes the remediation role, reads the current state of that resource, and builds a fix plan from what it actually finds rather than from the finding alone.

**2. Review what will change**

The dialog shows the resource's current state, the state it will be left in, a risk rating, and the exact AWS API calls the fix will make. Nothing has been changed at this point.

**3. Resolve any missing permissions**

If the plan needs an action the remediation role doesn't have, Comp AI lists the missing permissions and generates a CloudShell script that adds them. **Apply Fix** stays disabled until you run it and click **Recheck**.

**4. Confirm**

You must tick the acknowledgment box confirming you've reviewed the changes. **Apply Fix** stays disabled until you do.

**5. Comp AI applies the fix**

The plan runs against your account using short-lived STS credentials from the remediation role. If a step fails partway through, the steps already completed are rolled back automatically, so you're never left in a half-applied state.

### After a fix

Every fix is recorded in the **Remediations** section of the connection, with the commands that ran, the state before the change, who approved it, and when. The same event is written to your organization's audit log. Successful fixes can be undone from that list with **Rollback**.

### When a fix can't be automated

Not every finding can be fixed programmatically. Some require a decision only you can make; others turn out not to be automatable once Comp AI reads the real state of the resource. In both cases Comp AI shows step-by-step manual guidance instead of applying anything.

### Fixing a whole service at once

Any service group with failing findings offers **Fix All**. Choose which findings to include, confirm once, and Comp AI works through them in the background. Each fix is recorded individually, and you can skip any finding that is still queued.

### Guardrails

* **Nothing runs unattended** — scheduled scans are read-only; every fix needs a person
* **Destructive operations are blocked** — deleting buckets, terminating instances, and deleting IAM roles can never be part of a fix plan
* **Scoped permissions** — the remediation role grants a defined allowlist of actions, not administrator access
* **Permission-gated** — applying or rolling back a fix requires permission to update integrations in Comp AI

## What gets scanned

The AWS integration evaluates findings across a wide set of AWS services, including:

| Area | Services |
| - | - |
| Identity | IAM, IAM Access Analyzer, Cognito |
| Storage | S3, EBS, EFS, DynamoDB, RDS, Redshift, OpenSearch, ElastiCache |
| Compute | EC2 & VPC, Lambda, ECS & EKS, EMR, Elastic Beanstalk, CodeBuild, Step Functions |
| Network | VPC, ELB/ALB, CloudFront, API Gateway, Route 53, WAF, Network Firewall, Shield |
| Data security | KMS, Secrets Manager, ACM, Macie, Inspector |
| Observability | CloudTrail, CloudWatch, AWS Config, GuardDuty, Security Hub |
| Messaging | SNS, SQS, Kinesis, EventBridge, MSK |
| Other | Backup, ECR, Glue, Athena, SageMaker, Systems Manager, Transfer Family, AppFlow |

The **Services** tab inside each connection lets you enable or disable specific checks per service.

## Compliance frameworks

Findings are mapped to the controls used by:

* CIS AWS Foundations Benchmark
* SOC 2
* ISO 27001
* PCI DSS
* HIPAA (where applicable)

## Security model

* **Read-only by default** — the audit role cannot create, modify, or delete resources
* **External ID enforced** — Comp AI refuses to connect unless the External ID in your trust policy matches the one stored against your Comp AI organization
* **No static credentials** — Comp AI never stores AWS access keys; short-lived credentials are issued by STS on each scan
* **Revocable at any time** — deleting the IAM role in your account immediately cuts off access
* **Write access is opt-in and separate** — only the `CompAI-Remediator` role can change anything, only when you trigger a fix, and deleting that role leaves scanning untouched

## Troubleshooting

> **Access denied during AssumeRole**
>
> The most common cause is an External ID mismatch. Confirm the value in your role's trust policy matches the External ID shown in the Comp AI connection form. If you recently rotated it, re-run the CloudShell script.

> **Role ARN format error**
>
> Comp AI expects an ARN in the form `arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME`. Make sure you copied the role ARN from the CloudShell output, not the account or user ARN.

> **Findings missing for a specific service**
>
> Check that:
>
> 1. The role has `SecurityAudit` + `ViewOnlyAccess` attached (the script attaches both)
> 2. The region is enabled on your connection
> 3. The service is turned on in the **Services** tab for this connection

> **Auto-remediation isn't available**
>
> Auto-remediation requires the separate `CompAI-Remediator` role. Run the second CloudShell script shown in the UI, then paste its Role ARN into the **Remediation Role ARN** field.

> **A fix reports missing permissions**
>
> The remediation role covers the actions Comp AI needs for the services that support auto-fix. If a particular plan needs something outside that set, the dialog lists the missing actions and generates a CloudShell script that adds them. Run the script, then click **Recheck** — there's no need to recreate the role.

## Support

1. Email [support@trycomp.ai](mailto:support@trycomp.ai)
2. Join our [Discord community](https://discord.gg/compai)


# Azure Cloud Tests
Source: https://www.trycomp.ai/docs/cloud-tests/azure

Connect Microsoft Azure to Comp AI over OAuth (or a service principal) to run continuous cloud security checks against Microsoft Defender for Cloud.

## About the Azure integration

Comp AI connects to Microsoft Azure to pull security posture, identity, network, and compliance data from **Microsoft Defender for Cloud** and related services. All access is read-only.

The recommended connection method is **Microsoft OAuth** — you sign in with an Azure AD account that has the required roles, and Comp AI auto-detects your subscription. A **service principal** flow is also supported for customers who prefer to provision a dedicated identity.

> [!NOTE]
>
> Comp AI only ever issues `GET`/`list` API calls. It does not create, modify, or delete Azure resources, even when connected with a user that has write permissions.

## How access works

* **Primary flow**: OAuth 2.0 against `login.microsoftonline.com` using the `user_impersonation` scope on Azure Management API. Comp AI acts on behalf of the signed-in user, constrained by their Azure RBAC assignments.
* **Alternative flow**: An Azure AD App Registration (service principal) with a client secret, assigned the required roles on a subscription.
* **Scope**: A single Azure subscription per connection. Connect additional subscriptions by adding more connections.

## Prerequisites

Before connecting Azure, make sure you have:

1. An **Azure subscription** you want to monitor
2. A user (or service principal) with the following roles on that subscription:
   * **Reader** — read resource metadata
   * **Security Reader** — read Microsoft Defender for Cloud findings
   * **Monitoring Reader** — read activity logs, alerts, and metrics
3. **Microsoft Defender for Cloud** enabled on the subscription (the free tier is sufficient for most checks)
4. Admin access to your Comp AI workspace

## Connect with OAuth (recommended)

**1. Start the connection**

In Comp AI, go to **Cloud Tests → Azure → Connect**. Click **Sign in with Microsoft**.

**2. Consent to the requested scopes**

Sign in with an Azure AD account that has the roles listed above on the target subscription. Approve the consent screen.

**3. Verify detected subscription**

Comp AI automatically detects the subscriptions your account can access. The setup guide then runs checks for:

* **Subscription detected**
* **Required role assignments**
* **Defender for Cloud enabled**

Any blocking issue is shown with a link to the exact Azure portal blade to fix it.

**4. Run your first scan**

When all required steps pass, the first scan starts automatically. You can re-run it any time from the connection's page.

> [!NOTE]
>
> Microsoft OAuth uses the RBAC roles on your account. Granting **Reader + Security Reader + Monitoring Reader** is enough — you do **not** need Contributor or Owner.

## Connect with a service principal (alternative)

Use this flow if you want a dedicated non-human identity or your tenant restricts user OAuth consent.

**1. Register an app in Microsoft Entra ID**

In the Azure portal, go to **Microsoft Entra ID → App registrations → New registration**. Name it something like `comp-security-audit` and register.

**2. Create a client secret**

In the app, open **Certificates & secrets → New client secret**. Copy the secret **value** immediately — it is only shown once.

**3. Assign the three required roles**

Open your target subscription, go to **Access control (IAM) → Add role assignment**, and assign each of these roles to the app registration:

* **Reader**
* **Security Reader**
* **Monitoring Reader**

**4. Collect the four IDs**

From the Azure portal, copy:

* **Tenant ID** — Microsoft Entra ID → Overview
* **Client ID** — App registration → Overview (Application ID)
* **Client Secret** — the value from the previous step
* **Subscription ID** — Subscriptions → your subscription

**5. Paste into Comp AI**

In the Azure connection form, switch to the service principal option and paste the four values. Click **Save and Connect**.

## What gets scanned

The Azure integration evaluates findings across services including:

| Area | Services |
| - | - |
| Posture | Microsoft Defender for Cloud (assessments + alerts) |
| Identity | Microsoft Entra ID |
| Governance | Azure Policy |
| Data security | Key Vault, Storage Accounts, SQL Database, Cosmos DB |
| Compute | Virtual Machines, App Service, AKS, Container Registry |
| Network | Network Watcher (NSGs, flow logs) |
| Observability | Azure Monitor (activity logs, diagnostic settings) |

The **Services** tab inside the connection lets you enable or disable specific checks.

## Compliance frameworks

Findings are mapped to the controls used by:

* Microsoft Cloud Security Benchmark
* SOC 2
* ISO 27001
* PCI DSS
* HIPAA (where applicable)

## Security model

* **Read-only** — Comp AI makes no write calls, regardless of the roles you assign
* **Scoped to one subscription per connection** — a connection cannot read data outside the subscription it was created for
* **Secrets stay encrypted** — client secrets and refresh tokens are stored in an encrypted vault and never returned to the UI
* **Revocable at any time** — remove the role assignments in the Azure portal, or delete the connection in Comp AI

## Troubleshooting

> **Defender for Cloud shows no assessments**
>
> Defender for Cloud must be enabled on the subscription. Open the **Microsoft Defender for Cloud** blade, select the subscription, and confirm at least the free tier is turned on. Initial data can take up to 24 hours to appear.

> **Authentication failed**
>
> For OAuth: make sure your account still has the three required roles on the subscription — `User_impersonation` scope alone is not enough.
>
> For service principal: confirm the client secret has not expired and the app registration has not been disabled.

> **Subscription not detected after sign-in**
>
> Comp AI only sees subscriptions your signed-in account has access to. If you manage multiple subscriptions, sign in with an account that has **Reader** on the one you want to monitor, or use the service principal flow to target it explicitly.

> **Missing findings for a specific service**
>
> Check that the service is enabled under the **Services** tab for this connection. Some services also require Defender plans beyond the free tier — for example, Defender for Servers, SQL, or Containers.

## Support

1. Email [support@trycomp.ai](mailto:support@trycomp.ai)
2. Join our [Discord community](https://discord.gg/compai)


# GCP Cloud Tests
Source: https://www.trycomp.ai/docs/cloud-tests/gcp

Connect Google Cloud Platform to Comp AI over OAuth so findings from Security Command Center flow into your compliance posture.

## About the GCP integration

Comp AI connects to Google Cloud Platform over **OAuth 2.0** and reads findings from **Security Command Center (SCC)**. No service account JSON key is uploaded — you sign in with a Google account that has access to the organization and projects you want to monitor.

After you connect, Comp AI auto-detects your organization, lets you pick projects, then runs a setup step that enables the required APIs and verifies IAM access. Findings are mapped to common frameworks (SOC 2, ISO 27001, CIS GCP Foundations, PCI DSS, HIPAA).

> [!NOTE]
>
> Security Command Center is where all GCP findings originate. If SCC is not enabled at the organization, Comp AI cannot read findings regardless of connection method.

## How access works

* **Auth model**: OAuth 2.0 with Google, using the `cloud-platform` scope plus `openid`, `email`, `profile` for account identification. Refresh tokens are stored so scans can run without re-prompting.
* **Real permissions**: The OAuth scope only enables API calls — actual access is gated by the **IAM roles** assigned to the signed-in account. Comp AI only makes read calls.
* **Required role**: `roles/securitycenter.findingsViewer` on the **organization** (needed to read SCC findings). Project-level `roles/viewer` is also recommended.
* **Scope**: Comp AI scans the projects you select inside the organization the signed-in account belongs to.

## Prerequisites

Before connecting GCP, make sure you have:

1. A **GCP organization** with **Security Command Center** enabled — confirm at **GCP Console → Security → Risk Overview**
2. A Google account with:
   * `roles/securitycenter.findingsViewer` on the organization
   * `roles/viewer` (or equivalent) on the projects you want to scan
3. Permission to enable APIs on at least one project in the organization (so Comp AI's setup step can enable SCC, Cloud Resource Manager, and Service Usage APIs if they are not already on)
4. Admin access to your Comp AI workspace

> [!NOTE]
>
> If Security Command Center is not yet enabled, enable it first at [console.cloud.google.com/security/command-center](https://console.cloud.google.com/security/command-center).

## Connect GCP

**1. Start the connection**

In Comp AI, go to **Cloud Tests → GCP → Connect**. Click **Sign in with Google**.

**2. Authorize with Google**

Sign in with a Google account that meets the prerequisites above and approve the consent screen. Comp AI stores the resulting refresh token (never the password) so it can run scheduled scans.

**3. Select projects**

Comp AI auto-detects your organization and lists the projects that account can access. Pick the ones you want scanned — findings are scoped to those projects.

**4. Let auto-setup run**

Comp AI's setup guide runs automatically and shows a checklist:

* Connected via OAuth
* Organization detected
* Required APIs enabled (Security Command Center, Cloud Resource Manager, Service Usage)
* `roles/securitycenter.findingsViewer` granted at the organization level

Any step that fails is shown with a one-click **Resolve** button or a link to the exact GCP console page plus the `gcloud` command you can run to fix it manually.

**5. Run your first scan**

When all required steps pass, the first scan starts automatically. You can re-run it any time from the connection's page.

## What gets scanned

Comp AI consumes findings from Security Command Center across services including:

| Area | Services |
| - | - |
| Identity | IAM (over-privileged accounts, service account keys) |
| Storage | Cloud Storage (ACLs, public access, encryption) |
| Compute | Compute Engine, GKE |
| Network | VPC Network (firewall rules, flow logs), Cloud Armor |
| Data | Cloud SQL, BigQuery, Pub/Sub |
| Cryptography | Cloud KMS |
| Observability | Cloud Logging, Cloud Monitoring |
| DNS | Cloud DNS (DNSSEC) |

The **Services** tab inside the connection lets you enable or disable specific check categories.

## Compliance frameworks

Findings are mapped to the controls used by:

* CIS GCP Foundations Benchmark
* SOC 2
* ISO 27001
* PCI DSS
* HIPAA (where applicable)

## Security model

* **Read-only in practice** — Comp AI only issues read API calls against SCC and resource manager
* **IAM-bounded** — access is limited to what the signed-in account's IAM roles permit
* **Token storage** — refresh tokens are stored in an encrypted vault; they are never returned to the UI
* **Revocable at any time** — remove the IAM role, revoke the token at [myaccount.google.com/permissions](https://myaccount.google.com/permissions), or delete the connection in Comp AI

## Troubleshooting

> **Security Command Center findings not appearing**
>
> Confirm SCC is enabled at the organization level (not just one project). Open **GCP Console → Security → Risk Overview** and check that the organization shows findings.

> **Setup step: 'roles/securitycenter.findingsViewer' cannot be granted**
>
> The signed-in account does not have permission to manage IAM at the organization level. Ask a GCP organization admin to grant `roles/securitycenter.findingsViewer` to the account (or service account) you connected with. Copy the email shown in the setup guide — that is exactly who needs the role.

> **Setup step: APIs could not be enabled**
>
> The signed-in account lacks the `serviceusage.services.enable` permission on the target project. Either sign in with an account that has `roles/serviceusage.serviceUsageAdmin` on the project, or enable the three APIs manually from the [API Library](https://console.cloud.google.com/apis/library):
>
> * Security Command Center API
> * Cloud Resource Manager API
> * Service Usage API

> **No projects listed after OAuth**
>
> Comp AI only lists projects the signed-in account has IAM access to. Sign in with a different Google account, or ask an admin to add your account as `roles/viewer` on the relevant projects.

## Support

1. Email [support@trycomp.ai](mailto:support@trycomp.ai)
2. Join our [Discord community](https://discord.gg/compai)


# Cloud Tests
Source: https://www.trycomp.ai/docs/cloud-tests/index

Continuously assess your cloud posture by connecting AWS, Azure, and GCP to Comp AI.

## What Cloud Tests do

Cloud Tests connect your cloud accounts to Comp AI and continuously evaluate them against security and compliance controls. Each finding is mapped to the frameworks you track (SOC 2, ISO 27001, CIS, PCI DSS, HIPAA), so cloud misconfigurations show up directly in your compliance posture.

All connections are **read-only by default**. Comp AI only makes `GET` / `list` calls against each cloud provider unless you explicitly opt in to auto-remediation (AWS).

## Supported providers

> **[AWS](/docs/cloud-tests/aws)**
>
> Cross-account IAM role with External ID. No access keys stored.

> **[Azure](/docs/cloud-tests/azure)**
>
> Sign in with Microsoft OAuth, or provision a service principal.

> **[GCP](/docs/cloud-tests/gcp)**
>
> Sign in with Google OAuth. Findings flow from Security Command Center.

## How connections are authorized

| Provider | Connection method | What you provide |
| - | - | - |
| AWS | Cross-account IAM role (STS AssumeRole) | Role ARN + External ID (pre-filled in the UI) |
| Azure | OAuth 2.0 (primary) or service principal | Microsoft sign-in, or Tenant + Client ID + Secret + Sub ID |
| GCP | OAuth 2.0 | Google sign-in; org + projects auto-detected after consent |

## Common capabilities

Regardless of provider, each connection supports:

* **Continuous scanning** on a schedule, with on-demand re-scans
* **Per-service toggles** so you can enable only the checks you care about
* **Findings mapped to frameworks** (SOC 2, ISO 27001, CIS, PCI DSS, HIPAA)
* **Evidence collection** that plugs directly into the compliance module
* **Multiple connections per provider** so you can monitor multiple accounts, subscriptions, or orgs separately

## Next steps

* [Set up AWS](/docs/cloud-tests/aws)
* [Set up Azure](/docs/cloud-tests/azure)
* [Set up GCP](/docs/cloud-tests/gcp)


# Comp AI Device Agent
Source: https://www.trycomp.ai/docs/device-agent

Install the Comp AI Device Agent to monitor endpoint encryption, antivirus, password policy, and screen-lock compliance.

### About Comp AI Device Agent

Comp AI Device Agent is a lightweight desktop application that runs in your system tray and automatically monitors your device's security compliance. It checks your device configuration every hour and reports the results to your organization's Comp AI portal.

The agent checks four security areas:

| Security Check | What It Verifies |
| - | - |
| **Disk Encryption** | FileVault (macOS), BitLocker (Windows), or LUKS (Linux) is enabled |
| **Antivirus** | Active antivirus protection (XProtect, Windows Defender, ClamAV, etc.) |
| **Password Policy** | Minimum 8-character password enforced at the OS level |
| **Screen Lock** | Automatic screen lock activates within 15 minutes of inactivity |

Your device is **compliant** when all four checks pass.

> [!NOTE]
>
> The agent runs silently in your system tray and uses minimal system resources. It does not collect
> personal data, browsing history, or file contents.

> [!WARNING]
>
> **Password Policy can report that the minimum is unknown.** On Linux the minimum is only readable
> through `pam_pwquality`, which a stock Ubuntu install does not include. Where nothing enforces a
> configurable minimum, the agent says it *could not determine the minimum password length* and the
> check **fails** — it will not put a number on the card that the device does not actually enforce.
> See Troubleshooting below for what to do about it.

### System Requirements

| Requirement | Details |
| - | - |
| **Operating Systems** | macOS 14+, Windows 10+, Linux (Ubuntu 20.04+) |
| **Memory** | 512MB RAM minimum |
| **Storage** | 200MB available disk space |

### Installation

> **Step 1: Download the Agent**
>
> Log in to your organization's [Employee Portal](https://portal.trycomp.ai) and navigate to the **Device Agent** task. Click **Download Agent** to get the installer for your operating system.
>
> * **macOS**: Downloads a `.dmg` file. If you have an Apple Silicon Mac (M1/M2/M3/M4), the portal selects the correct version automatically. You can also switch between Apple Silicon and Intel using the dropdown.
> * **Windows**: Downloads a `.exe` installer.
> * **Linux**: Downloads a `.deb` package.

> **Step 2: Install the Agent**
>
> **macOS**: Double-click the downloaded `.dmg` file and drag the Comp AI Device Agent to your Applications folder.
>
> **Windows**: Double-click the downloaded `.exe` file and follow the installation wizard.
>
> **Linux**: Install the downloaded `.deb` package using your package manager or by double-clicking it:
>
> ```bash theme={null}
> sudo dpkg -i CompAI-Device-Agent-amd64.deb
> ```

> **Step 3: Sign In**
>
> After installation, the agent opens a sign-in window. Log in with your work email using the same method you use for the Employee Portal (email OTP, Google, or Microsoft).
>
> ![Device Agent Sign In](https://mintcdn.com/bubbaaiinc/ZLIYkYd_dV1Kt3fR/images/device-agent-sign-in.png?fit=max\&auto=format\&n=ZLIYkYd_dV1Kt3fR\&q=85\&s=2a8f67ffed888f0a5cf3a1f52c6103a3)
>
> Once signed in, the agent automatically:
>
> 1. Registers your device with your organization(s)
> 2. Runs the first compliance check immediately
> 3. Starts checking every hour in the background

### Using the Device Agent

After signing in, the agent lives in your system tray (menu bar on macOS, system tray on Windows/Linux). Click the tray icon to open the status window.

![Device Agent Status Window](https://mintcdn.com/bubbaaiinc/ZLIYkYd_dV1Kt3fR/images/device-agent-status.png?fit=max\&auto=format\&n=ZLIYkYd_dV1Kt3fR\&q=85\&s=96da6f8cf4fa815fdcc97cc22c2d7278)

The status window shows:

* **Compliance status** — whether your device is compliant or needs attention
* **Individual checks** — each of the four security checks with Pass/Fail status
* **Remediation options** — for any failing check, the agent offers a way to fix it

#### Tray Icon Status

| Icon Color | Meaning |
| - | - |
| **Green** | Device is compliant — all checks passing |
| **Red** | Device is non-compliant — one or more checks failing |
| **Gray** | Agent is not signed in or checks are loading |

#### Fixing Failing Checks

When a check fails, the agent provides remediation options depending on what can be done automatically:

| Option | Description |
| - | - |
| **Fix** | The agent fixes the issue automatically |
| **Fix (Admin)** | The agent fixes it but may prompt for your system password |
| **Open Settings** | Opens the relevant OS settings pane so you can fix it manually |
| **View Guide** | Shows step-by-step instructions to resolve the issue |

> [!TIP]
>
> After fixing a failing check, click **Run Checks Now** to verify the fix immediately instead of
> waiting for the next hourly check.

#### Password Advisory on a Passing Check

The Password Policy check can also show a note on a check that is **passing**. If the agent has seen the enforced minimum go up and can date that change, and your password was last set before that date, the card adds a sentence saying so. On macOS it also offers a **Change Password** button that opens System Settings → Touch ID & Password; on Linux the same note appears with steps instead of a button. Windows does not show this note.

This never fails the check and never makes your device non-compliant. It is not a claim that your password is too short — the agent cannot read the length of anyone's password on any platform. All it knows is that your password predates the rule, so it may be shorter than the rule now requires. Changing your password clears the note at the next check.

#### Tray Menu Options

Right-click (or click on macOS) the tray icon to access:

* **Run Checks Now** — trigger an immediate compliance check
* **View Details** — open the status window
* **Start at Login** — toggle whether the agent launches automatically when you log in (enabled by default)
* **Sign Out** — sign out of the agent
* **Quit** — close the agent completely

> [!WARNING]
>
> If you quit or sign out of the agent, your device will stop reporting compliance status to your
> organization. Your security administrator may follow up if your device stops checking in.

### Verifying on the Portal

After the agent runs its first check, you can verify your device compliance status on the Employee Portal. The **Device Agent** task shows your device name, platform, and whether all security checks are passing.

The portal updates automatically — it polls your device status every 30 seconds while the page is open.

### Troubleshooting

> **Agent won't sign in**
>
> * Make sure you're using the same email address you use for the Employee Portal
> * Check your internet connection
> * Try quitting the agent completely and reopening it
> * If using Google or Microsoft sign-in, make sure popups are not blocked

> **Checks are failing unexpectedly**
>
> * Click **Run Checks Now** to refresh the results
> * Review the failing check details — the agent shows what it detected
> * Use the remediation option provided (Fix, Open Settings, or View Guide)
> * Some changes (like enabling FileVault) require a restart to take effect

> **Password Policy says Comp AI could not determine the minimum password length**
>
> This means the agent could not establish a minimum it is willing to stand behind. Rather than report a number the device does not enforce, it says so and the check fails. There are a few reasons it happens: nothing on the device enforces a configurable minimum; a configuration file could not be read, so a setting that overrides the rest may be hiding in it; a value is written in a form libpwquality itself rejects; or a minimum is configured but is not actually binding — `enforcing = 0` makes libpwquality warn about a weak password and accept it anyway, and `local_users_only` applies the rules only to accounts in `/etc/passwd`. When the agent was specifically denied permission to read a file, the card says that instead.
>
> The failing check's **View Guide** option names which of these it found, so start there.
>
> On Linux — including a stock Ubuntu install, which has no `pam_pwquality` in its PAM stack — an administrator can install and configure it:
>
> ```bash theme={null}
> sudo apt install libpam-pwquality              # Debian/Ubuntu
> sudo dnf install libpwquality                  # Fedora/RHEL
> sudo mkdir -p /etc/security/pwquality.conf.d
> echo 'minlen = 8' | sudo tee /etc/security/pwquality.conf.d/50-comp-ai.conf
> ```
>
> Then click **Run Checks Now**. The failing check's **View Guide** option shows these same steps, and reports which setting is overriding the drop-in when one is.

> **Agent is not visible in the system tray**
>
> * **macOS**: Look in the menu bar at the top of your screen. The icon may be hidden — check the overflow area (click the `>>` or similar)
> * **Windows**: Click the up arrow in the system tray to see hidden icons
> * **Linux**: Check your desktop environment's system tray or notification area
> * The agent may need to be reopened from your Applications folder

> **Portal shows device as non-compliant even though agent shows all checks passing**
>
> * Wait up to 30 seconds for the portal to refresh
> * Click **Run Checks Now** in the agent to trigger a fresh report
> * Check that the agent is signed in (tray icon should be green, not gray)

### Migrating from FleetDM

If your device previously had the FleetDM agent (fleetd) installed, you should uninstall it after setting up the new Comp AI Device Agent. The new agent fully replaces FleetDM, and having both running is unnecessary.

Follow the official uninstall guide for your platform: [How to uninstall fleetd](https://fleetdm.com/guides/how-to-uninstall-fleetd)

### Manual Evidence Collection

For users who cannot install the agent on their device, manual evidence of device settings is required. Below are the required pieces of evidence and where to obtain them.

> **Windows Manual Evidence**
>
> #### Windows 10 & 11
>
> **Enable BitLocker**
>
> 1. Press **Start** → type **Manage BitLocker** → open it.\
>    Take a screenshot of the BitLocker Drive Encryption window showing "On" for the C: drive.
> 2. Select the drive (usually C:) → click **Turn on BitLocker**.
> 3. Save the recovery key to Microsoft Account / USB / secure location.
> 4. Restart if prompted.
>
> **Screen Lock after 15 Minutes**
>
> 1. Press **Start** → **Settings** → **Personalization** → **Lock screen**.
> 2. Scroll down → click **Screen timeout settings**.\
>    Take a screenshot showing the screen timeout set to 15 minutes.
> 3. Set **Screen turns off** = 15 minutes.
> 4. In **Settings** → **Accounts** → **Sign-in options** → ensure **Require sign-in** is set to *"When PC wakes up from sleep"*.\
>    Take a screenshot of the Sign-in Options page showing this setting.
>
> **Minimum Password Length (Local Policy)**
>
> 1. Press Win + R, type `secpol.msc`, press Enter.
> 2. Go to **Account Policies** → **Password Policy**.
> 3. Set **Minimum password length** = 8+.\
>    Take a screenshot of the Password Policy window with "Minimum password length" = 8 or more.
>
> *(If using Microsoft/AD/Azure, enforce via policy centrally and screenshot the policy compliance in the admin portal.)*
>
> **Automatic Security Updates**
>
> 1. **Settings** → **Update & Security** → **Windows Update**.
> 2. Select **Advanced options** → make sure Automatic updates are enabled.\
>    Take a screenshot of the Windows Update settings page showing automatic updates turned on.
>
> **Antivirus (Windows Defender)**
>
> 1. **Settings** → **Update & Security** → **Windows Security**.
>
> 2. Open **Virus & threat protection** → ensure **Real-time protection** is on.\
>    Take a screenshot of the Windows Security window showing Real-time protection is ON.
>
> > [!NOTE]
> >
> > Evidence gathered manually will be uploaded as a comment and attachment to the "Secure Devices" and "Device List" tasks with the user's email of the device the evidence is for.

> **macOS Manual Evidence**
>
> #### macOS (Monterey, Ventura, Sonoma, Sequoia)
>
> **Enable FileVault**
>
> 1. Open **System Settings** (or **System Preferences** in older versions).
> 2. Go to **Privacy & Security** → **FileVault**.
> 3. Click **Turn On FileVault** → enter password.
> 4. Record recovery key.\
>    Take a screenshot of the FileVault settings page showing "FileVault is enabled for the disk."
>
> **Screen Auto-lock (15 min)**
>
> 1. **System Settings** → **Lock Screen**.
> 2. Set **Start screen saver when inactive** = 15 minutes.\
>    Take a screenshot showing the setting at 15 minutes.
> 3. Set **Require password after sleep or screen saver begins** = *Immediately*.\
>    Take a screenshot showing "Require password immediately" is selected.
>
> **Minimum Password Length**
>
> 1. Native macOS UI doesn't enforce this; requires **Terminal** or **MDM**.
> 2. `sudo pwpolicy -setglobalpolicy "minChars=8"` — this adds a minimum alongside the stock FileVault policy rather than replacing the policy set, which is what `pwpolicy -setaccountpolicies` would do.
> 3. If set via Terminal, take a screenshot of `pwpolicy getaccountpolicies` confirming the policy.
> 4. If enforced by MDM (Jamf, Intune, etc.), screenshot the compliance screen from the MDM portal.
>
> **Automatic Security Updates**
>
> 1. **System Settings** → **General** → **Software Update**.
> 2. Click **Automatic Updates** → enable all options (Install Security Responses & System files, etc.).\
>    Take a screenshot of the Automatic Updates options screen with all toggles enabled.
>
> **Antivirus (XProtect built-in)**
>
> 1. macOS automatically runs **XProtect** in the background.
>
> 2. Simply ensure macOS is **fully updated**.\
>    Take a screenshot of the Software Update page showing the Mac is up to date.
>
> > [!NOTE]
> >
> > Evidence gathered manually will be uploaded as a comment and attachment to the "Secure Devices" and "Device List" tasks with the user's email of the device the evidence is for.

> **Linux Manual Evidence**
>
> #### Ubuntu 20.04+ / Debian-based
>
> **Enable LUKS Disk Encryption**
>
> 1. LUKS encryption is typically configured during OS installation.
> 2. To verify, run: `lsblk -o NAME,TYPE,FSTYPE | grep crypt`\
>    Take a screenshot showing the encrypted volume.
>
> **Screen Lock (15 min)**
>
> 1. Open **Settings** → **Privacy** → **Screen Lock**.
> 2. Set **Automatic Screen Lock Delay** = 15 minutes.\
>    Take a screenshot showing the screen lock delay setting.
>
> **Password Policy**
>
> Linux enforces a minimum password length through `pam_pwquality`, not through `/etc/login.defs` — nothing reads `PASS_MIN_LEN`, so a screenshot of it is not evidence that anything is enforced.
>
> 1. Confirm `pam_pwquality` is in the PAM stack:
>    ```bash theme={null}
>    grep pam_pwquality /etc/pam.d/common-password /etc/pam.d/system-auth
>    ```
>    Stock Ubuntu does not ship it. An administrator installs it with `sudo apt install libpam-pwquality` (Debian/Ubuntu) or `sudo dnf install libpwquality` (Fedora/RHEL).
> 2. Set the minimum in a drop-in file — the same file the agent's Fix writes:
>    ```bash theme={null}
>    sudo mkdir -p /etc/security/pwquality.conf.d
>    echo 'minlen = 8' | sudo tee /etc/security/pwquality.conf.d/50-comp-ai.conf
>    ```
> 3. Confirm nothing overrides it. A `minlen=` argument on the `pam_pwquality` line, a `minlen` in `/etc/security/pwquality.conf`, or a drop-in that sorts after `50-comp-ai.conf` each win over this file. A positive `dcredit`, `ucredit`, `lcredit` or `ocredit` anywhere in the stack lets a password be shorter than `minlen` in exchange for mixing character types, and `enforcing = 0` or `local_users_only` stops the minimum binding at all.\
>    Take a screenshot of the drop-in's contents and of the `pam_pwquality` line.
>
> **Antivirus**
>
> 1. Verify ClamAV or another antivirus is installed and running:
>    ```bash theme={null}
>    systemctl status clamav-daemon
>    ```
>
> 2. Alternatively, show AppArmor or SELinux is enforcing:
>    ```bash theme={null}
>    sudo aa-status    # AppArmor
>    getenforce         # SELinux
>    ```
>    Take a screenshot of the output showing active protection.
>
> > [!NOTE]
> >
> > Evidence gathered manually will be uploaded as a comment and attachment to the "Secure Devices" and "Device List" tasks with the user's email of the device the evidence is for.

### Support

If you have questions or run into issues with the Device Agent, contact your IT administrator or reach out to us at [hello@trycomp.ai](mailto:hello@trycomp.ai).


# Aikido Security
Source: https://www.trycomp.ai/docs/integrations/aikido

Connect Aikido to automate security evidence in Comp AI

## Overview

The Aikido Security integration syncs vulnerability and repository scanning data into Comp AI, so compliance tasks can be automatically satisfied with continuous evidence.

## What Comp AI Collects

### Secure Code evidence

* Open security issues (by severity)
* Repository scanning activity
* Stale scans (repos not scanned in over 7 days)

### Monitoring and Alerting evidence

* Issue count thresholds (configurable)
* Severity breakdown summaries

## Configuration Options

After connecting, you can configure:

* **Minimum severity to fail on** (low, medium, high, critical)
* **Maximum allowed open issues** (threshold check)
* **Repositories to monitor** (optional filter)
* **Include snoozed issues** (optional)

## Verify It Works

Checks run on their own, and the manual re-run lives on the task the check feeds — not on the integration page.

1. Open the Aikido integration in Comp AI and find the **Evidence tasks** section
2. Click **Open** on one of those tasks
3. In the task's **App Automations** card, click **Run** on an Aikido check
4. The check expands to show the run and the passing or failing evidence it collected

![Example check run](https://mintcdn.com/bubbaaiinc/6VwDQO5lCxknRCcW/images/example_where_you_run_aikido.png?fit=max\&auto=format\&n=6VwDQO5lCxknRCcW\&q=85\&s=49b3104db5b541164be4d471d34b21ae)

If a check fails with `HTTP 401: Unauthorized`, verify the Client ID and Client Secret and ensure the required permissions are enabled in Aikido.

## References

* Aikido API docs: [https://apidocs.aikido.dev/reference](https://apidocs.aikido.dev/reference)


# Authentication Reference
Source: https://www.trycomp.ai/docs/integrations/authentication

Complete guide to all authentication types supported by the integration platform

## Overview

The integration platform supports **4 authentication strategies**. Choose based on what the third-party service offers.

## Quick Comparison

| Type | When to Use | User Setup | Platform Setup | Token Refresh |
| - | - | - | - | - |
| **OAuth 2.0** | Service has OAuth | 1-click connect | Admin configures OAuth app | Auto |
| **API Key** | Service uses API keys | User enters key | None | N/A (keys don't expire) |
| **Basic Auth** | Service uses username/password | User enters creds | None | N/A |
| **Custom** | Complex multi-field auth | User enters multiple fields | None | N/A |

***

## OAuth 2.0

**Best for:** GitHub, Google, Linear, Vercel, most modern SaaS

### Configuration

```typescript theme={null}
auth: {
  type: 'oauth2',
  config: {
    // Required
    authorizeUrl: 'https://provider.com/oauth/authorize',
    tokenUrl: 'https://provider.com/oauth/token',
    scopes: ['read:user', 'read:org'],

    // Optional
    pkce: false,                    // Use PKCE flow? (default: false)
    clientAuthMethod: 'body',       // 'body' or 'header' (default: 'body')
    supportsRefreshToken: true,     // Can tokens be refreshed? (default: true)

    // Additional params sent during authorization
    authorizationParams: {
      access_type: 'offline',      // Request refresh token
      prompt: 'consent',           // Force consent screen
    },

    // Additional params sent during token exchange
    tokenParams: {
      grant_type: 'authorization_code',
    },

    // Admin setup instructions (Markdown)
    setupInstructions: `...`,

    // URL to create OAuth app
    createAppUrl: 'https://provider.com/apps/new',

    // Custom settings (advanced)
    customSettings: [
      {
        id: 'app_name',
        label: 'App Name',
        type: 'text',
        required: true,
        token: '{APP_NAME}', // Replaces in authorizeUrl
      },
    ],
  },
},
```

### Key Options Explained

#### `pkce` (Proof Key for Code Exchange)

**When to use:** Some providers require it (GitHub does NOT, Auth0 does)

```typescript theme={null}
pkce: true; // Generates code_verifier and code_challenge
```

#### `clientAuthMethod`

**How to send client credentials during token exchange:**

* `'body'` (default): Send as form fields

  ```
  POST /token
  client_id=...&client_secret=...
  ```

* `'header'`: Send as Basic Auth header
  ```
  POST /token
  Authorization: Basic base64(client_id:client_secret)
  ```

**Use `header` for:** OAuth providers that require Basic Auth (some enterprise providers)

#### `supportsRefreshToken`

**Controls token refresh behavior:**

* `true` (default): Platform auto-refreshes tokens before expiry
* `false`: Tokens are long-lived (e.g., GitHub Personal Access Tokens)

**Set to `false` if:** Provider doesn't support refresh tokens or tokens never expire

#### `customSettings`

**For providers with non-standard OAuth requirements:**

**Example:** Rippling needs app name in authorize URL:

```typescript theme={null}
authorizeUrl: 'https://api.rippling.com/connect/authorize/{APP_NAME}',
customSettings: [
  {
    id: 'app_name',
    label: 'Rippling App Name',
    type: 'text',
    required: true,
    token: '{APP_NAME}',
  },
],
```

Platform admin enters `app_name` → Platform replaces `{APP_NAME}` in URL.

### Access Token in Checks

```typescript theme={null}
run: async (ctx: CheckContext) => {
  // Access token is automatically available
  const token = ctx.accessToken;

  // ctx.fetch() automatically adds Bearer token
  const data = await ctx.fetch('/api/endpoint');

  // For custom headers
  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${ctx.accessToken}`,
    },
  });
};
```

***

## API Key

**Best for:** Simple REST APIs with static API keys (e.g., Stripe, SendGrid)

### Configuration

```typescript theme={null}
auth: {
  type: 'api_key',
  config: {
    in: 'header',           // or 'query'
    name: 'X-API-Key',      // Header name or query param name
    prefix: 'Bearer ',      // Optional prefix (e.g., "Bearer ", "Token ")
  },
},
```

### Key Options

#### `in` - Where to send the API key

**Header (recommended):**

```typescript theme={null}
in: 'header',
name: 'X-API-Key',

// Results in:
// X-API-Key: your-api-key-value
```

**Query parameter:**

```typescript theme={null}
in: 'query',
name: 'api_key',

// Results in:
// GET /endpoint?api_key=your-api-key-value
```

**Use query for:** APIs that don't accept custom headers (rare)

#### `prefix` - Add a prefix to the key

```typescript theme={null}
prefix: 'Bearer ',   // Common for tokens
prefix: 'Token ',    // Some APIs use this
prefix: '',          // No prefix (default)

// Example with Bearer:
// Authorization: Bearer sk_live_abc123...
```

### Credential Field

User will see a form field to enter the API key:

```typescript theme={null}
// Automatically generated credential field
{
  id: 'api_key',
  label: 'API Key',
  type: 'password',
  required: true,
  placeholder: 'sk_live_...',
  helpText: 'Found in Settings → API Keys',
}
```

### Access in Checks

```typescript theme={null}
run: async (ctx: CheckContext) => {
  // API key is automatically added to requests
  const data = await ctx.fetch('/endpoint');

  // Or access it directly
  const apiKey = ctx.credentials.api_key;
};
```

***

## Basic Auth

**Best for:** APIs using username/password authentication (e.g., some internal tools)

### Configuration

```typescript theme={null}
auth: {
  type: 'basic',
  config: {
    usernameField: 'username',  // Default, can customize
    passwordField: 'password',  // Default, can customize
  },
},
```

### Credential Fields

Users will see two fields:

```typescript theme={null}
// Automatically generated
[
  {
    id: 'username',
    label: 'Username',
    type: 'text',
    required: true,
  },
  {
    id: 'password',
    label: 'Password',
    type: 'password',
    required: true,
  },
];
```

### Custom Field Names

```typescript theme={null}
auth: {
  type: 'basic',
  config: {
    usernameField: 'email',      // Use 'email' instead of 'username'
    passwordField: 'api_token',  // Use 'api_token' instead of 'password'
  },
},
```

### Access in Checks

```typescript theme={null}
run: async (ctx: CheckContext) => {
  // Basic Auth header is automatically added
  // Authorization: Basic base64(username:password)
  const data = await ctx.fetch('/endpoint');

  // Or access credentials directly
  const username = ctx.credentials.username;
  const password = ctx.credentials.password;
};
```

***

## Custom Auth

**Best for:** Complex authentication requiring multiple fields (AWS IAM Role, Azure Service Principal, GCP Service Account)

### Configuration

```typescript theme={null}
auth: {
  type: 'custom',
  config: {
    description: 'AWS IAM Role for cross-account access',

    credentialFields: [
      {
        id: 'roleArn',
        label: 'IAM Role ARN',
        type: 'text',
        required: true,
        placeholder: 'arn:aws:iam::123456789012:role/MyRole',
        helpText: 'The ARN of the IAM role to assume',
      },
      {
        id: 'externalId',
        label: 'External ID',
        type: 'password',
        required: true,
        helpText: 'Unique identifier for security',
      },
      {
        id: 'region',
        label: 'AWS Region',
        type: 'combobox',
        required: true,
        placeholder: 'Select or type...',
        helpText: 'Primary region for API calls',
        options: [
          { value: 'us-east-1', label: 'US East (N. Virginia)' },
          { value: 'eu-west-1', label: 'Europe (Ireland)' },
        ],
      },
    ],

    setupInstructions: `## Setup Guide

1. Create IAM role in AWS
2. Copy the Role ARN
3. Generate External ID
4. Enter credentials below`,
  },
},
```

### Field Types

| Type | UI Component | When to Use | Example |
| - | - | - | - |
| `text` | Text input | Single-line text | Project ID, Account ID |
| `password` | Password input (hidden) | Secrets, tokens | API keys, passwords |
| `textarea` | Multi-line textarea | Long text, JSON | Service account JSON key |
| `select` | Dropdown (fixed options) | Choose from list | Environment (prod/dev) |
| `combobox` | Dropdown + custom input | Choose or type | AWS region, timezone |
| `number` | Number input | Numeric values | Port, timeout |
| `url` | URL input (with validation) | Web addresses | Webhook URL, API endpoint |

### Field Options

```typescript theme={null}
{
  id: 'field_name',           // Unique identifier (snake_case)
  label: 'Field Label',       // Shown to user
  type: 'text',              // See table above
  required: true,            // Is this field mandatory?
  placeholder: 'example...',  // Placeholder text
  helpText: 'Explain where to find this', // Help text below field

  // For select/combobox only:
  options: [
    { value: 'val1', label: 'Option 1' },
    { value: 'val2', label: 'Option 2' },
  ],
}
```

### Access in Checks

```typescript theme={null}
run: async (ctx: CheckContext) => {
  // All fields available as key-value pairs
  const roleArn = ctx.credentials.roleArn;
  const externalId = ctx.credentials.externalId;
  const region = ctx.credentials.region;

  // Custom authentication logic
  const client = await createCustomClient({
    roleArn,
    externalId,
    region,
  });
};
```

***

## Choosing an Auth Type

### Decision Tree

```
Does the service have OAuth?
├─ YES → Use OAuth 2.0
│   └─ Best UX, auto token refresh, secure
│
└─ NO
    │
    Does it use a single API key?
    ├─ YES → Use API Key
    │   └─ Simple, user just pastes key
    │
    └─ NO
        │
        Does it use username + password?
        ├─ YES → Use Basic Auth
        │   └─ Two fields, encoded automatically
        │
        └─ NO → Use Custom Auth
            └─ Multiple fields, full control
```

### Comparison: OAuth vs API Key

| Aspect | OAuth 2.0 | API Key |
| - | - | - |
| **User Experience** | Best (1-click) | OK (find & paste key) |
| **Security** | Tokens expire & refresh | Long-lived secrets |
| **Platform Setup** | Admin must configure | None needed |
| **Revocation** | User revokes in provider | User must regenerate key |
| **Scope Control** | Request specific permissions | Key has fixed permissions |

**Recommendation:** Use OAuth if the service supports it.

### Comparison: Basic Auth vs Custom

| Aspect | Basic Auth | Custom Auth |
| - | - | - |
| **Fields** | 2 (username/password) | Any number |
| **Encoding** | Auto (Base64) | Manual in check code |
| **Use Case** | Simple APIs | Complex auth (AWS, Azure) |
| **Setup** | Minimal config | Define all fields |

**Use Basic Auth for:** Simple username/password APIs\
**Use Custom Auth for:** Multi-field credentials, service accounts, IAM roles

***

## Examples by Service Type

### Cloud Providers (AWS, Azure, GCP)

**Use:** Custom Auth (service accounts, IAM roles)

**Why:** These services use multi-field credentials that need custom authentication logic. OAuth is possible but service accounts are the recommended approach for programmatic access.

### SaaS Tools (GitHub, Linear, Notion)

**Use:** OAuth 2.0

**Why:** Best user experience, tokens auto-refresh, users can revoke access easily.

### Internal Tools / Legacy APIs

**Use:** Basic Auth or API Key

**Why:** Simpler services often use these methods. Choose based on what the API supports.

***

## Advanced OAuth Options

### PKCE (Proof Key for Code Exchange)

**What it is:** Extra security for OAuth (prevents authorization code interception)

**When to enable:**

```typescript theme={null}
pkce: true; // Enable for: Auth0, Okta, some enterprise providers
pkce: false; // Default for: GitHub, Google, Linear
```

**How it works:** Platform generates a random `code_verifier`, hashes it to create `code_challenge`, sends challenge during authorization, sends verifier during token exchange.

### Client Authentication Method

**How platform authenticates itself to the provider:**

**Body (default):**

```http theme={null}
POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&client_id=...&client_secret=...
```

**Header (Basic Auth):**

```http theme={null}
POST /token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...
```

**Use `header` when:** Provider documentation explicitly requires Basic Auth for client authentication.

### Custom Authorization Parameters

**Add extra params to the authorization URL:**

```typescript theme={null}
authorizationParams: {
  access_type: 'offline',    // Google: Request refresh token
  prompt: 'consent',         // Force consent screen (always request scopes)
  response_mode: 'query',    // How to return auth code
}
```

**Common use cases:**

* `access_type: 'offline'` - Google APIs (get refresh token)
* `prompt: 'consent'` - Always show consent screen (good for testing)
* Custom provider-specific params

***

## Security Best Practices

### API Keys

* Use `type: 'password'` for sensitive fields (hidden input)
* Store in credential vault (auto-encrypted)
* Never log API keys
* Add help text explaining where to find/generate the key

### OAuth

* Request minimum scopes needed
* Use `access_type: 'offline'` for refresh tokens
* Set `supportsRefreshToken: true` to auto-refresh
* Explain scope requirements in setup instructions

### Basic Auth

* Both username and password are required
* Password field is auto-hidden
* Credentials are auto-encoded to Base64
* Never log passwords

### Custom Auth

* Mark sensitive fields as `type: 'password'`
* Validate all required fields in checks
* Handle missing fields gracefully
* Don't expose credential values in logs/errors

***

## Complete OAuth Example

```typescript theme={null}
auth: {
  type: 'oauth2',
  config: {
    authorizeUrl: 'https://github.com/login/oauth/authorize',
    tokenUrl: 'https://github.com/login/oauth/access_token',
    scopes: ['repo', 'read:org', 'read:user'],
    pkce: false,
    clientAuthMethod: 'body',
    supportsRefreshToken: false, // GitHub tokens don't expire
    authorizationParams: {
      allow_signup: 'false', // Don't show sign-up on consent
    },
    setupInstructions: `## Create GitHub OAuth App

1. Go to https://github.com/settings/developers
2. Click "New OAuth App"
3. Enter:
   - Application name: Your app name
   - Homepage URL: https://yourapp.com
   - Callback URL: [shown below]
4. Click "Register application"
5. Copy Client ID and generate Client Secret
6. Paste both below`,
    createAppUrl: 'https://github.com/settings/apps/new',
  },
},
```

***

## Testing Your Auth

### OAuth

1. Configure platform credentials in `/admin/integrations`
2. Go to `/integrations` and click Connect
3. Should redirect to provider OAuth screen
4. Authorize → Should redirect back successfully
5. Check connection is active

### API Key / Basic / Custom

1. Go to `/integrations` and click Connect
2. Form should show your credential fields
3. Enter test credentials
4. Connection should be created successfully
5. Run a check to verify credentials work

### Debug OAuth Issues

Check API logs for:

* `OAuth completed for [provider]` - Success
* `OAuth callback error` - Authorization failed
* `Token exchange failed` - Bad client credentials
* `Invalid state` - State mismatch (check callback URL)

***

## Summary

**Choose your auth type:**

* **Service has OAuth?** → Use OAuth 2.0
* **Single API key?** → Use API Key
* **Username/password?** → Use Basic Auth
* **Multiple fields or complex?** → Use Custom Auth

**OAuth is best when available** - better UX, security, and user control.


# Writing Checks Reference
Source: https://www.trycomp.ai/docs/integrations/checks

Complete guide to writing compliance checks

## Overview

Checks are the core of integrations - they validate compliance against external services and report findings.

**A check:**

* Fetches data from the service API
* Analyzes it for compliance issues
* Reports findings (failures) or passing results (successes)
* Can map to compliance tasks for auto-completion

***

## Check Structure

```typescript theme={null}
export const yourCheck: IntegrationCheck = {
  // Metadata
  id: 'unique-check-id',
  name: 'Human-Readable Check Name',
  description: 'What this check validates',
  
  // Optional: Map to a task template
  taskMapping: TASK_TEMPLATES.twoFactorAuth,
  
  // Default severity for findings (can override per finding)
  defaultSeverity: 'medium',
  
  // User-configurable variables
  variables: [],
  
  // The check logic
  run: async (ctx: CheckContext) => {
    // Your code here
  },
};
```

***

## CheckContext API Reference

### HTTP Methods

```typescript theme={null}
// GET request
const data = await ctx.fetch<ResponseType>('/endpoint');

// POST request
const result = await ctx.post<ResponseType>('/endpoint', { body: 'data' });

// PUT request
const updated = await ctx.put<ResponseType>('/endpoint/:id', { updates });

// PATCH request
const patched = await ctx.patch<ResponseType>('/endpoint/:id', { partial });

// DELETE request
await ctx.delete('/endpoint/:id');
```

### Pagination

**Auto-pagination** (for standardized APIs):

```typescript theme={null}
// Fetches all pages automatically
const allItems = await ctx.fetchAllPages<Item>('/items');
```

**Page number pagination:**

```typescript theme={null}
const allItems = await ctx.fetchWithPageNumbers<Item>({
  path: '/items',
  maxPages: 100,
  pageParam: 'page',
  perPageParam: 'per_page',
  perPage: 100,
});
```

**Cursor pagination:**

```typescript theme={null}
const allItems = await ctx.fetchWithCursor<Item>({
  path: '/items',
  maxPages: 100,
  cursorParam: 'cursor',
  dataPath: 'data.items',
  cursorPath: 'data.nextCursor',
});
```

**Link header pagination:**

```typescript theme={null}
const allItems = await ctx.fetchWithLinkHeader<Item>('/items', {
  maxPages: 100,
});
```

### GraphQL

```typescript theme={null}
const data = await ctx.graphql<QueryResult>(
  `query {
    users {
      id
      email
      twoFactorEnabled
    }
  }`,
  { limit: 100 } // Optional variables
);
```

### Logging

```typescript theme={null}
ctx.log('Info message', { optional: 'metadata' });
ctx.warn('Warning message', { data });
```

**Logs appear in:**

* API console during development
* Trigger.dev dashboard for background jobs
* Check run logs in database

### State Storage

**For checks that need to remember data between runs:**

```typescript theme={null}
// Save state
await ctx.state.set('last_check_time', new Date().toISOString());

// Retrieve state
const lastCheck = await ctx.state.get<string>('last_check_time');
```

**Use for:** Incremental checks, rate limit tracking, caching

### Available Data

```typescript theme={null}
ctx.accessToken;      // OAuth access token (if OAuth)
ctx.credentials;      // All credentials as object
ctx.variables;        // User-configured variables
ctx.connectionId;     // Current connection ID
ctx.organizationId;   // Current organization ID
ctx.metadata;         // Connection metadata (e.g., OAuth team info)
```

***

## Reporting Findings

### ctx.fail() - Report an Issue

```typescript theme={null}
ctx.fail({
  title: 'Issue Title (shown in UI)',
  resourceType: 'repository',        // Type of resource
  resourceId: 'org/repo-name',      // Unique resource ID
  severity: 'high',                 // critical | high | medium | low | info
  description: 'What is wrong',
  remediation: 'How to fix it',
  evidence: {                       // Supporting data
    currentValue: false,
    expectedValue: true,
    checkedAt: new Date(),
  },
});
```

**Required fields:**

* `title` - Short summary
* `resourceType` - Category of resource
* `resourceId` - Unique identifier
* `severity` - How serious is this?
* `description` - What's wrong
* `remediation` - How to fix

**Optional fields:**

* `evidence` - Any relevant data (stored as JSON)

### ctx.pass() - Report Success

```typescript theme={null}
ctx.pass({
  title: 'Check Passed',
  resourceType: 'repository',
  resourceId: 'org/repo-name',
  description: 'What was validated successfully',
  evidence: {
    checkedItems: 10,
    allPassed: true,
  },
});
```

**When to use:**

* Check completed successfully
* Informational results (not just absence of findings)
* Evidence for auditors

**When NOT to use:**

* Just because no issues found (that's implied if no `fail()` calls)
* For intermediate steps (use `ctx.log()` instead)

***

## Severity Levels

| Level | When to Use | Example |
| - | - | - |
| `critical` | Immediate security risk, compliance violation | No encryption, public S3 buckets |
| `high` | Serious issue, needs urgent fix | 2FA disabled, admin without MFA |
| `medium` | Important but not urgent | Outdated dependencies, missing alerts |
| `low` | Minor issue, best practice | Naming conventions, documentation |
| `info` | Informational, no action needed | Configuration review, statistics |

**Default severity** can be overridden per finding:

```typescript theme={null}
export const check: IntegrationCheck = {
  defaultSeverity: 'medium',  // Default for this check
  
  run: async (ctx) => {
    ctx.fail({
      severity: 'critical',  // Override for this specific finding
      // ...
    });
  },
};
```

***

## Task Mapping

**Auto-complete compliance tasks when checks pass:**

```typescript theme={null}
import { TASK_TEMPLATES } from '../../../task-mappings';

export const twoFactorCheck: IntegrationCheck = {
  id: 'two-factor-auth',
  taskMapping: TASK_TEMPLATES['2fa'],  // Maps to "2FA" task
  
  run: async (ctx) => {
    // Check 2FA status
    const allUsersHave2FA = checkTwoFactor();
    
    if (allUsersHave2FA) {
      // When this passes, the "2FA" task is auto-marked as done
      ctx.pass({
        title: 'All Users Have 2FA',
        // ...
      });
    }
  },
};
```

**Available task templates:** See `packages/integration-platform/src/task-mappings.ts` for the full list.

**Benefits:**

* Automatic task completion
* Reduces manual work
* Keeps tasks in sync with real state

**When to use:** When the check directly validates what a task requires.

***

## Error Handling

### User-Friendly Errors

**Bad:**

```typescript theme={null}
catch (error) {
  ctx.fail({
    title: 'Error',
    description: error.message,  // Raw API error
    remediation: 'Fix it',       // Vague
  });
}
```

**Good:**

```typescript theme={null}
catch (error) {
  const errorMessage = error instanceof Error ? error.message : String(error);
  ctx.log(`API Error: ${errorMessage}`);  // Log full error
  
  if (errorMessage.includes('403') || errorMessage.includes('PERMISSION_DENIED')) {
    ctx.fail({
      title: 'Permission Denied',
      description: 'Your account lacks necessary permissions',
      remediation: 'Grant the "Security Viewer" role in provider settings → IAM → Add Role',
      evidence: { error: errorMessage },  // Raw error in evidence (not description)
    });
    return;
  }
  
  // Generic fallback
  ctx.fail({
    title: 'Failed to Fetch Data',
    description: 'An error occurred while checking your account',
    remediation: 'Verify your connection is active and try reconnecting',
    evidence: { error: errorMessage },
  });
}
```

### Common Error Patterns

**Permission denied:**

```typescript theme={null}
if (errorMessage.includes('403') || errorMessage.includes('PERMISSION_DENIED')) {
  ctx.fail({
    title: 'Permission Denied',
    description: 'Your account does not have access to this resource',
    remediation: 'Grant [specific role] in provider settings',
    severity: 'high',
  });
  return;
}
```

**Resource not found:**

```typescript theme={null}
if (errorMessage.includes('404') || errorMessage.includes('NOT_FOUND')) {
  ctx.log(`Resource not found: ${resourceId}`);
  // Don't fail - just skip it
  return;
}
```

**Rate limited:**

```typescript theme={null}
if (errorMessage.includes('429') || errorMessage.includes('rate limit')) {
  ctx.fail({
    title: 'Rate Limited',
    description: 'API rate limit exceeded',
    remediation: 'Wait a few minutes and try again',
    severity: 'low',
  });
  return;
}
```

**Service not enabled:**

```typescript theme={null}
if (errorMessage.includes('not enabled') || errorMessage.includes('not subscribed')) {
  ctx.pass({  // Use pass() for informational, not fail()
    title: 'Service Not Enabled',
    description: 'Security Hub is not enabled in your account',
    evidence: { note: 'Enable Security Hub to get findings' },
  });
  return;
}
```

***

## Performance Tips

### Batch API Calls

**Bad:**

```typescript theme={null}
for (const repo of repos) {
  const details = await ctx.fetch(`/repos/${repo}`);  // N API calls
}
```

**Good:**

```typescript theme={null}
// Fetch all at once if API supports it
const details = await ctx.post('/repos/batch', { repos: repos.map(r => r.id) });

// Or use Promise.all (but be careful with rate limits)
const details = await Promise.all(
  repos.slice(0, 10).map(r => ctx.fetch(`/repos/${r}`))
);
```

### Cache Results

```typescript theme={null}
run: async (ctx) => {
  // Check if we fetched recently
  const lastFetch = await ctx.state.get<string>('last_users_fetch');
  const cacheValid = lastFetch && 
    Date.now() - new Date(lastFetch).getTime() < 3600000; // 1 hour
  
  let users;
  if (cacheValid) {
    users = await ctx.state.get<User[]>('cached_users');
  } else {
    users = await ctx.fetch<User[]>('/users');
    await ctx.state.set('cached_users', users);
    await ctx.state.set('last_users_fetch', new Date().toISOString());
  }
  
  // Use cached users
}
```

***

## Testing Checks

### Manual Testing

1. Connect the integration with real credentials
2. Run the check from Cloud Tests or a task
3. Verify:
   * No errors in API logs
   * Findings appear correctly
   * Remediation steps are clear
   * Evidence contains useful data

### Error Case Testing

Test that your check handles:

* Missing permissions (403 errors)
* Invalid credentials (401 errors)
* Resource not found (404 errors)
* Rate limiting (429 errors)
* Empty datasets (no resources to check)
* Malformed responses

### Edge Cases

* User has no resources (empty org)
* All resources are compliant (no findings)
* Variables not configured (required variables missing)
* Dynamic options return empty list

***

## Examples

### Simple Check (No External Data)

```typescript theme={null}
export const configCheck: IntegrationCheck = {
  id: 'config-check',
  name: 'Configuration Review',
  defaultSeverity: 'low',
  variables: [],
  
  run: async (ctx) => {
    ctx.pass({
      title: 'Configuration Reviewed',
      resourceType: 'integration',
      resourceId: ctx.connectionId,
      description: 'Integration configuration has been reviewed',
      evidence: { reviewedAt: new Date() },
    });
  },
};
```

### Data Fetching Check

```typescript theme={null}
export const securityCheck: IntegrationCheck = {
  id: 'security-check',
  name: 'Security Settings',
  defaultSeverity: 'high',
  variables: [],
  
  run: async (ctx) => {
    const settings = await ctx.fetch<SecuritySettings>('/security');
    
    if (!settings.twoFactorRequired) {
      ctx.fail({
        title: '2FA Not Required',
        resourceType: 'security-setting',
        resourceId: 'two-factor',
        severity: 'high',
        description: '2FA is not enforced for all users',
        remediation: 'Enable 2FA requirement in Settings → Security → Require 2FA',
        evidence: { currentSetting: settings.twoFactorRequired },
      });
    } else {
      ctx.pass({
        title: '2FA Required',
        resourceType: 'security-setting',
        resourceId: 'two-factor',
        description: '2FA is enforced for all users',
        evidence: { setting: settings.twoFactorRequired },
      });
    }
  },
};
```

### Iterating Over Resources

```typescript theme={null}
export const repoCheck: IntegrationCheck = {
  id: 'repo-security',
  name: 'Repository Security',
  variables: [targetReposVariable],
  
  run: async (ctx) => {
    const targetRepos = ctx.variables.target_repos as string[];
    
    if (!targetRepos?.length) {
      ctx.fail({
        title: 'No Repositories Selected',
        description: 'Select repositories to monitor in integration settings',
        resourceType: 'configuration',
        resourceId: 'target_repos',
        severity: 'medium',
        remediation: 'Go to Manage → Settings → Select Repositories',
        evidence: {},
      });
      return;
    }
    
    ctx.log(`Checking ${targetRepos.length} repositories`);
    
    for (const repoName of targetRepos) {
      try {
        const repo = await ctx.fetch<Repo>(`/repos/${repoName}`);
        
        if (!repo.branchProtectionEnabled) {
          ctx.fail({
            title: `No Branch Protection on ${repoName}`,
            resourceType: 'repository',
            resourceId: repoName,
            severity: 'high',
            description: 'Main branch has no protection rules',
            remediation: `Go to ${repoName} → Settings → Branches → Add Protection`,
            evidence: { repo: repoName, protected: false },
          });
        } else {
          ctx.pass({
            title: `Branch Protection on ${repoName}`,
            resourceType: 'repository',
            resourceId: repoName,
            description: 'Main branch is protected',
            evidence: { repo: repoName, rules: repo.protectionRules },
          });
        }
      } catch (error) {
        ctx.log(`Skipping ${repoName}: ${error}`);
        // Don't fail the whole check if one repo is inaccessible
      }
    }
  },
};
```

***

## Best Practices

### Findings vs Passing Results

**Only create findings for actual issues:**

```typescript theme={null}
// Good
if (hasIssue) {
  ctx.fail({ ... });
}
// No else - absence of findings implies success

// Bad
if (hasIssue) {
  ctx.fail({ ... });
} else {
  ctx.pass({ ... });  // Don't create passing results for every check
}
```

**When to use `ctx.pass()`:**

* Summary results (e.g., "100 users checked, all have 2FA")
* Evidence for auditors (e.g., "Access review completed on 2024-12-08")
* Don't use for absence of findings

**For cloud tests:** Only `fail()` results are shown. Passing results are filtered out.

### Resource Types

Use consistent resource types:

| Type | Examples |
| - | - |
| `repository` | GitHub/GitLab repos |
| `user` | Users, accounts, members |
| `team` | Teams, groups, org units |
| `project` | Projects, workspaces |
| `deployment` | Deployments, releases |
| `security-setting` | Security configs |
| `iam-policy` | Access policies |
| `alert` | Monitoring alerts |
| `configuration` | Integration settings |

### Evidence

**Include useful data for auditors:**

```typescript theme={null}
evidence: {
  // Good
  userId: user.id,
  userEmail: user.email,
  twoFactorEnabled: user.twoFactorEnabled,
  lastLogin: user.lastLoginAt,
  checkedAt: new Date().toISOString(),
  
  // Avoid
  rawResponse: entireApiResponse,  // Too much data
  password: user.password,         // Never include secrets
}
```

### Remediation Steps

**Be specific and actionable:**

```typescript theme={null}
// Vague
remediation: 'Fix the security settings'

// Specific
remediation: 'Go to Settings → Security → Enable 2FA → Click "Require for all users"'

// With link
remediation: 'Enable branch protection: https://github.com/org/repo/settings/branch_protection_rules/new'
```

***

## Performance Considerations

### Don't Over-Fetch

```typescript theme={null}
// Bad - Fetch all repos even if user only selected a few
const allRepos = await ctx.fetchAllPages('/repos');
const selectedRepos = allRepos.filter(r => targetRepos.includes(r.name));

// Good - Only fetch what's needed
const selectedRepos = await Promise.all(
  targetRepos.map(name => ctx.fetch(`/repos/${name}`))
);
```

### Rate Limits

The platform handles retries automatically, but you can help:

```typescript theme={null}
// Batch requests when possible
const results = await ctx.post('/batch', { ids: [1, 2, 3, 4, 5] });

// Sequential requests are slower but safer
for (const id of ids) {
  const result = await ctx.fetch(`/item/${id}`);
  // Process one at a time
}
```

### Timeouts

Checks have a **15-minute timeout** (Trigger.dev default). For long-running checks:

```typescript theme={null}
// Process in batches
const BATCH_SIZE = 50;
for (let i = 0; i < items.length; i += BATCH_SIZE) {
  const batch = items.slice(i, i + BATCH_SIZE);
  await processBatch(batch);
  ctx.log(`Processed batch ${i / BATCH_SIZE + 1}`);
}
```

***

## Examples from Built-in Integrations

### GitHub: Secret Scanning

```typescript theme={null}
export const secretScanningCheck: IntegrationCheck = {
  id: 'secret-scanning',
  name: 'Secret Scanning Alerts',
  taskMapping: TASK_TEMPLATES.secureSecrets,
  variables: [targetReposVariable],
  
  run: async (ctx) => {
    const targetRepos = ctx.variables.target_repos as string[];
    
    for (const repoName of targetRepos) {
      const alerts = await ctx.fetch<Alert[]>(
        `/repos/${repoName}/secret-scanning/alerts`,
      );
      
      for (const alert of alerts) {
        if (alert.state === 'open') {
          ctx.fail({
            title: `Secret Exposed in ${repoName}`,
            resourceType: 'secret-alert',
            resourceId: alert.number.toString(),
            severity: 'critical',
            description: `${alert.secret_type} secret detected in repository`,
            remediation: 'Rotate the exposed secret and remove it from git history',
            evidence: {
              secretType: alert.secret_type,
              createdAt: alert.created_at,
              url: alert.html_url,
            },
          });
        }
      }
    }
  },
};
```

### AWS: Security Hub Findings

```typescript theme={null}
export const securityHubCheck: IntegrationCheck = {
  id: 'security-hub-findings',
  name: 'Security Hub Findings',
  variables: [],
  
  run: async (ctx) => {
    // Custom AWS auth - create client manually
    const aws = await createAWSClient(ctx.credentials);
    
    const findings = await getSecurityHubFindings(aws.securityHub);
    
    for (const finding of findings) {
      ctx.fail({
        title: finding.Title,
        resourceType: finding.ResourceType,
        resourceId: finding.ResourceId,
        severity: mapSeverity(finding.Severity),
        description: finding.Description,
        remediation: finding.Remediation?.Recommendation?.Text || 'See AWS Console',
        evidence: {
          awsAccountId: finding.AwsAccountId,
          region: finding.Region,
          findingId: finding.Id,
        },
      });
    }
  },
};
```

***

## Checklist for a Good Check

* [ ] Clear, descriptive ID (kebab-case)
* [ ] User-friendly name
* [ ] Helpful description
* [ ] Proper error handling for common cases
* [ ] Meaningful resource types and IDs
* [ ] Specific remediation steps
* [ ] Useful evidence (not too much, not too little)
* [ ] Appropriate severity levels
* [ ] Task mapping (if applicable)
* [ ] Variables for user configuration (if needed)
* [ ] Tested with real API credentials
* [ ] Handles edge cases (empty data, missing resources)

***

## Summary

**Checks are the heart of integrations.** Write them to be:

* **Focused**: One check = one compliance validation
* 🧑‍💻 **User-friendly**: Clear errors, actionable remediation
* 🔒 **Secure**: Handle credentials properly, never log secrets
* ⚡ **Efficient**: Batch requests, handle pagination
* 🧪 **Tested**: Verify with real credentials and edge cases

Great checks = happy users = successful integration!


# Contributing Integrations
Source: https://www.trycomp.ai/docs/integrations/contributing

Guidelines for contributing new integrations to the platform

## Before You Start

**Check if the integration already exists** by looking in `packages/integration-platform/src/manifests/`.

**Good integration candidates:**

* Service has a public API
* Service provides compliance/security data
* Maps to existing compliance tasks
* Widely used in B2B/enterprise

**Not a good fit:**

* Service requires paid enterprise plan for API access
* No security/compliance data available via API
* Consumer-focused service with no business use case

## Contribution Checklist

Your PR should include:

### 1. Integration Manifest

**Required:**

* [ ] Manifest file (`manifests/your-service/index.ts`)
* [ ] Valid integration ID (kebab-case, unique)
* [ ] Clear name and description
* [ ] Working logo URL
* [ ] Documentation URL
* [ ] Correct category
* [ ] Proper auth configuration

### 2. At Least One Check

**Required:**

* [ ] Check file(s) in `checks/` folder
* [ ] Descriptive check IDs
* [ ] Clear error messages
* [ ] Proper error handling
* [ ] Task mapping (if applicable)
* [ ] Evidence includes useful data

### 3. Types

**Required:**

* [ ] TypeScript types file (`types.ts`)
* [ ] Types for API responses
* [ ] Types for credentials
* [ ] No `any` types

### 4. Testing

**Required:**

* [ ] Tested with real credentials
* [ ] OAuth flow works (if OAuth)
* [ ] Checks run successfully
* [ ] Error cases handled gracefully
* [ ] Variables work (if using variables)

**Include in PR description:**

* Screenshot of successful connection
* Screenshot of check results
* Test account details (if applicable)

### 5. Documentation

**Required:**

* [ ] Setup instructions in manifest (for OAuth)
* [ ] Clear credential field labels and help text
* [ ] Variable help text explains what they do
* [ ] Remediation steps are actionable

**Nice to have:**

* [ ] MDX doc in `packages/docs/integrations/your-service.mdx`
* [ ] Examples in PR description

### 6. Code Quality

**Required:**

* [ ] TypeScript with no errors
* [ ] ESLint passes
* [ ] Follows existing code patterns
* [ ] No hardcoded values
* [ ] Proper error handling

## PR Template

```markdown theme={null}
## Integration: [Service Name]

### Overview
- **Service**: [Service Name]
- **Auth Type**: OAuth 2.0 / API Key / Custom
- **Category**: Cloud / Identity & Access / Developer Tools
- **Checks**: [List check names]

### What This Integration Does
[Brief description of what checks are included and what they validate]

### Testing
- [x] Connected successfully with OAuth/credentials
- [x] All checks run without errors
- [x] Error handling works for common failure cases
- [x] Variables configured and working (if applicable)

**Screenshots:**
[Add screenshots of connection flow and check results]

### Task Mapping
- Check: [Check Name] → Task: [Task Template Name]
- Check: [Check Name] → Task: [Task Template Name]

### Breaking Changes
None / [Describe any breaking changes]

### Notes
[Any additional context, limitations, or future improvements]
```

## Review Criteria

Reviewers will check for:

### Functionality

* Integration connects successfully
* Checks run and produce expected results
* OAuth flow works (if OAuth)
* Error states are handled

### Code Quality

* TypeScript types are correct
* No `any` types
* Follows existing patterns
* Proper error handling
* Code is readable and maintainable

### User Experience

* Clear, friendly error messages
* Helpful remediation steps
* Good variable labels and help text
* Reasonable defaults

### Security

* Credentials handled securely
* API calls use HTTPS
* No secrets in code
* Proper scope requests (OAuth)

## Common Review Feedback

### "Add error handling for X"

**Before:**

```typescript theme={null}
const data = await ctx.fetch('/endpoint');
// Process data
```

**After:**

```typescript theme={null}
try {
  const data = await ctx.fetch('/endpoint');
  // Process data
} catch (error) {
  ctx.fail({
    title: 'Failed to Fetch Data',
    // ... proper error handling
  });
}
```

### "Make error messages user-friendly"

**Before:**

```typescript theme={null}
description: `API error: ${error.message}` // Raw error
```

**After:**

```typescript theme={null}
description: 'Your account does not have permission to access this resource',
remediation: 'Grant the "Admin" role in Service Settings → Users',
evidence: { error: errorMessage }, // Store raw error in evidence
```

### "Add task mapping"

**Before:**

```typescript theme={null}
export const check: IntegrationCheck = {
  id: 'two-factor',
  // No task mapping
};
```

**After:**

```typescript theme={null}
import { TASK_TEMPLATES } from '../../../task-mappings';

export const check: IntegrationCheck = {
  id: 'two-factor',
  taskMapping: TASK_TEMPLATES['2fa'], // Maps to 2FA task
};
```

## Getting Your PR Merged

1. **Create a draft PR early** - Get feedback before spending too much time
2. **Test thoroughly** - Include test results in PR
3. **Follow the template** - Makes review faster
4. **Respond to feedback** - Reviewers are trying to help
5. **Keep it focused** - One integration per PR

## After Your PR is Merged

**For OAuth integrations:**

* Platform admins need to configure OAuth credentials
* Your integration will show "Coming Soon" until configured
* Update documentation with OAuth setup steps

**For all integrations:**

* Integration appears in the integrations page
* Users can connect and start using it
* Checks run automatically or on-demand

## Questions?

* Check existing integrations for patterns
* Ask in discussions/issues
* Tag maintainers for help

Thank you for contributing!


# GitHub
Source: https://www.trycomp.ai/docs/integrations/github

Connect GitHub to automate code security evidence in Comp AI

## Overview

The GitHub integration monitors repository security, branch protection, dependency updates and organization settings, so code security compliance tasks are satisfied with continuous evidence.

Comp AI ships two GitHub integrations:

* **GitHub App** (recommended) — you install the Comp AI GitHub App and pick which repositories to share. The App has fine-grained, **read-only** permissions.
* **GitHub** — the original OAuth App integration. GitHub's OAuth Apps have no read-only scope for private repositories, so this one requests the broad `repo` scope, which also grants write access.

Both run the same checks; only the way the token is obtained differs. Existing GitHub (OAuth) connections keep working, so switching to the App is optional.

## Connect

### GitHub App

1. Go to **Integrations** and open **GitHub App**
2. Click **Connect** and authorize the Comp AI app on GitHub
3. If the App is not installed yet, GitHub shows the install screen — choose the organization and select the repositories to share
4. GitHub returns you to Comp AI with the connection active

### GitHub (OAuth)

1. Go to **Integrations** and open **GitHub**
2. Click **Connect** and authorize with a GitHub account that can see the repositories you want monitored (requested scopes: `read:org`, `repo`, `read:user`)

Self-hosting Comp AI? Both integrations need your own GitHub credentials — see [Self-hosting OAuth](/docs/integrations/oauth-setup).

## Configuration Options

Open **Settings** on the integration and configure:

* **Repositories to monitor** (required) — the checks run against this list. Values are `owner/repo`, optionally with branches: `acme/api:main`, or `acme/api:main,release`. Without a branch, `main` is assumed. Only repositories owned by a GitHub **organization** are listed — personal repositories are not.
* **Recent PR window (days)** — default `180`. How far back the branch protection check looks when deciding whether pull requests are recent.
* **Fail on open alerts at severity** — default `High or above`. The Dependabot check fails when the repository has open alerts at or above this severity; alerts below it are informational.

### Before any repository is selected

While the list is empty the message you get depends on which check you look at:

* **Branch Protection Enabled** and **2FA Enforcement** fail with **No repositories configured**
* **Code Scanning** and **Sanitized Inputs** fail with **No repositories selected**
* **Dependabot Security Updates Enabled** does not stop — with an empty list it falls back to every repository in every organization the connection can see, so it reports findings for repositories you never selected

Select at least one repository and all five checks run against that list only.

## What Comp AI Collects

### Code Security evidence

* **Branch Protection Enabled** — the selected branches have protection rules configured
* **Code Scanning** — CodeQL (default setup or a custom workflow) or a third-party SARIF uploader is configured
* **Sanitized Inputs** — a supported input-validation library is in use (JS/TS, Python or PHP), including monorepo subdirectories
* **2FA Enforcement** — every member of the organizations that own the selected repositories has two-factor authentication enabled

### Dependency Management evidence

* **Dependabot Security Updates Enabled** — Dependabot security updates are enabled and open alerts stay under your severity threshold

Checks run daily and after you change settings, and each one maps to a compliance task that is completed automatically while the check passes.

## Verify It Works

Checks run on their own, and the manual re-run lives on the task the check feeds — not on the integration page.

1. Open the GitHub integration in Comp AI and find the **Evidence tasks** section
2. Click **Open** on one of those tasks
3. In the task's **App Automations** card, click **Run** on a GitHub check
4. The check expands to show the run and the passing or failing evidence it collected

## Troubleshooting

**`Could not access repository "owner/repo"`** — the connection cannot see that repository. On the GitHub App, re-open the App's installation on GitHub and add the repository to the selected list. On the OAuth integration, confirm the authorizing user has access to it, then reconnect.

**An organization's repositories are missing from the picker** — organizations that enforce SAML SSO are skipped until your GitHub session is authorized for them. Authorize the organization on GitHub, then reload the settings.

## References

* GitHub REST API: [https://docs.github.com/en/rest](https://docs.github.com/en/rest)
* [Self-hosting OAuth](/docs/integrations/oauth-setup)


# Integrations
Source: https://www.trycomp.ai/docs/integrations/index

Extensible platform for building compliance check integrations

## Overview

Integrations let you connect third-party services (GitHub, AWS, Google Cloud, etc.) to automatically run compliance checks and collect evidence.

**Key Features:**

* Extensible architecture for adding new integrations
* Multiple auth strategies (OAuth, API keys, custom credentials)
* Automated compliance checks that map to tasks
* Background execution via Trigger.dev
* Type-safe with full TypeScript support

## How It Works

### 1. Integration Manifests

Each integration is defined by a **manifest** that describes:

* Authentication method (OAuth, API key, custom)
* Available compliance checks
* User-configurable variables
* API endpoints and headers

### 2. Checks

Checks are compliance validations that run against the external service. For example:

* GitHub: "Are all repos using branch protection?"
* AWS: "Are there any high-severity findings in Security Hub?"
* Google Workspace: "Do all users have 2FA enabled?"

### 3. Task Mapping

Checks can map to compliance task templates. When a check passes, the associated task is auto-completed.

Example: The GitHub "Branch Protection" check maps to the "Code Changes" task. When the check passes, the "Code Changes" task is automatically marked as done.

### 4. Connection Flow

**OAuth integrations:**

1. User clicks "Connect"
2. Redirected to provider's OAuth screen
3. User authorizes
4. Token stored securely (encrypted at rest)
5. Checks run automatically (if no variables needed) or after user configures variables

**Custom auth integrations:**

1. User clicks "Connect"
2. User enters credentials (API keys, service account, etc.)
3. Credentials stored securely (encrypted at rest)
4. Checks run automatically (if no variables needed) or after user configures variables

### 5. Auto-Run Logic

After connecting an integration:

* If all required variables are configured → Checks run automatically via Trigger.dev
* If variables needed → User configures them → Checks run
* Checks also run daily via scheduled Trigger.dev task

## Architecture

```
Integrations
├── Manifests (define integrations)
│   ├── Auth config (OAuth, API key, custom)
│   ├── Checks (compliance validations)
│   └── Variables (user configuration)
├── Runtime (execute checks)
│   ├── Check context (API, logging, reporting)
│   └── Check runner (orchestration)
├── API (NestJS backend)
│   ├── Connections (manage user connections)
│   ├── OAuth (handle OAuth flow)
│   ├── Checks (run checks)
│   └── Variables (manage user settings)
└── Trigger Tasks (background execution)
    ├── run-connection-checks (auto-run after connect)
    ├── run-task-integration-checks (daily scheduled)
    └── sync-employees-schedule (daily employee sync)
```

## Built-in Integrations

### Cloud Providers

* **AWS** - Security Hub findings
* **Azure** - Microsoft Defender for Cloud
* **GCP** - Security Command Center

### Identity & Access

* **Google Workspace** - User compliance, 2FA checks
* **Rippling** - Employee sync

### Developer Tools

* **GitHub** - Code security, branch protection, Dependabot
* **Vercel** - Deployment monitoring
* **Linear** - Team privacy, SSO checks

## Next Steps

> **[Writing Integrations](/docs/integrations/writing-integrations)**
>
> Learn how to create your own integration

> **[Contributing](/docs/integrations/contributing)**
>
> Contribute integrations to the platform

> **[Self-Hosting OAuth](/docs/integrations/oauth-setup)**
>
> Configure OAuth for self-hosted deployments


# OAuth Configuration for Self-Hosters
Source: https://www.trycomp.ai/docs/integrations/oauth-setup

Platform admin guide to enabling OAuth integrations

> [!WARNING]
>
> This guide is for **platform administrators** self-hosting the application. If you're a regular user trying to connect an integration, this doesn't apply to you - just click "Connect" and follow the prompts.

## Overview

OAuth integrations require **platform-level credentials** that you (the admin) configure once in your deployment. After that, all users can connect their accounts with a single click.

**Without OAuth configured:** Integration shows "Coming Soon" (disabled)\
**With OAuth configured:** Users click "Connect" → OAuth flow → Done!

## Quick Start

For each OAuth integration you want to enable:

1. Create OAuth app with the provider
2. Copy Client ID and Client Secret
3. Go to `/admin/integrations` in your deployment
4. Find the integration → Click "Configure"
5. Paste credentials → Save

That's it! Users can now connect.

***

## Provider Setup Guides

### GitHub

**1. Create OAuth App**

1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Click **New OAuth App**
3. Fill in:
   * **Application name**: Your app name (e.g., "Comp AI at Acme Corp")
   * **Homepage URL**: `https://yourapp.com`
   * **Authorization callback URL**: `https://yourapp.com/v1/integrations/oauth/callback`
4. Click **Register application**
5. Copy the **Client ID**
6. Click **Generate a new client secret** → Copy it

**2. Add to Platform**

1. Go to `/admin/integrations` in your deployment
2. Find **GitHub** in the list
3. Click **Configure OAuth**
4. Paste **Client ID** and **Client Secret**
5. Click **Save**

**3. Test**

1. Go to `/integrations`
2. Find GitHub
3. Click **Connect** (should no longer say "Coming Soon")
4. Authorize with your GitHub account
5. Connection successful!

**Important:** The callback URL must exactly match what you enter in your deployment.

***

### Google (Workspace & Cloud Platform)

> [!TIP]
>
> Google Workspace and Google Cloud Platform can **share the same OAuth app**. Create it once, use it for both!

**1. Create Google Cloud Project**

1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Create a new project (or select existing)
3. Name it something like "Comp AI OAuth"

**2. Configure OAuth Consent Screen**

1. Go to **APIs & Services** → **OAuth consent screen**
2. Select **Internal** (if using Google Workspace) or **External**
3. Fill in:
   * **App name**: Your app name
   * **User support email**: Your email
   * **Developer contact**: Your email
4. Don't add scopes manually - we request them dynamically
5. Save and continue

**3. Create OAuth Credentials**

1. Go to **APIs & Services** → **Credentials**
2. Click **Create Credentials** → **OAuth client ID**
3. Select **Web application**
4. Name: "Comp AI Web"
5. **Authorized redirect URIs**: `https://yourapp.com/v1/integrations/oauth/callback`
6. Click **Create**
7. Copy **Client ID** and **Client Secret**

**4. Enable Required APIs**

In the same GCP project, enable these APIs:

* **Admin SDK API** (for Google Workspace)
* **Cloud Resource Manager API** (for GCP)
* **Security Command Center API** (for GCP)

Go to **APIs & Services** → **Library** and search for each.

**5. Add to Platform (Google Workspace)**

1. Go to `/admin/integrations`
2. Find **Google Workspace**
3. Click **Configure OAuth**
4. Paste Client ID and Client Secret
5. Save

**6. Add to Platform (GCP) - Optional**

1. In the same admin page
2. Find **Google Cloud Platform**
3. Click **Configure OAuth**
4. Paste the **same** Client ID and Client Secret
5. Save

**User Requirements:**

* **Google Workspace**: User must be a Workspace admin
* **GCP**: User must have Viewer + Security Center Findings Viewer roles at org level

***

### Linear

**1. Create OAuth App**

1. Go to [Linear API Settings](https://linear.app/settings/api)
2. Click **Create new OAuth application**
3. Fill in:
   * **Name**: Your app name
   * **Callback URLs**: `https://yourapp.com/v1/integrations/oauth/callback`
4. Click **Create**
5. Copy **Client ID** and **Client Secret**

**2. Add to Platform**

1. Go to `/admin/integrations`
2. Find **Linear** → **Configure OAuth**
3. Paste credentials → Save

***

### Vercel

**1. Create Integration**

1. Go to [Vercel Integrations Console](https://vercel.com/dashboard/integrations/console)
2. Click **Create Integration**
3. Fill in:
   * **Name**: Your app name
   * **Redirect URL**: `https://yourapp.com/v1/integrations/oauth/callback`
4. Create → Copy **Client ID**, **Client Secret**, and **Integration Slug**

**2. Add to Platform**

1. Go to `/admin/integrations`
2. Find **Vercel** → **Configure OAuth**
3. Paste Client ID and Client Secret
4. In **Custom Settings**, add the **Integration Slug**
5. Save

**Note:** Vercel requires an integration slug as a custom setting.

***

### Rippling

> [!WARNING]
>
> Rippling requires marketplace approval and takes 1-2 weeks.

**1. Request Marketplace App**

1. Contact Rippling support or your account manager
2. Request a marketplace integration
3. Provide:
   * App name
   * Callback URL: `https://yourapp.com/v1/integrations/oauth/callback`
   * App description
4. Wait for approval (1-2 weeks)

**2. Receive Credentials**

Rippling will provide:

* Client ID
* Client Secret
* App Name (your marketplace app identifier)

**3. Add to Platform**

1. Go to `/admin/integrations`
2. Find **Rippling** → **Configure OAuth**
3. Paste Client ID and Client Secret
4. In **Custom Settings**, add the **App Name** provided by Rippling
5. Save

***

## Non-OAuth Integrations

These integrations don't require platform-level OAuth setup:

### AWS, Azure, GCP (Service Accounts)

**No platform configuration needed!**

Users provide their own:

* **AWS**: IAM Role ARN, External ID
* **Azure**: Service Principal credentials
* **GCP**: OAuth (but users connect with their own Google account)

***

## Troubleshooting

### Integration Shows "Coming Soon"

**Cause:** OAuth credentials not configured\
**Fix:** Go to `/admin/integrations` → Configure Client ID/Secret

### OAuth Callback Error

**Cause:** Callback URL mismatch\
**Fix:** Ensure the URL in the OAuth app exactly matches your deployment:

* OAuth app: `https://yourapp.com/v1/integrations/oauth/callback`
* Your deployment URL: `https://yourapp.com`

They must match!

### "Invalid Client" Error

**Cause:** Wrong Client ID or Secret\
**Fix:** Double-check you copied both correctly, no extra spaces

### Users Can't Authorize (Google)

**Cause:** APIs not enabled in your GCP project\
**Fix:** Enable Admin SDK API (Workspace) or Cloud APIs (GCP)

### "Access Denied" After Connecting

**Cause:** User lacks required permissions in their account\
**Fix:** User needs to grant IAM roles in the provider (check integration docs for required roles)

***

## Security Notes

### Where Credentials are Stored

OAuth Client IDs and Secrets are stored in the **database**, encrypted at rest using AES-256-GCM.

**Not in environment variables** - This allows:

* Multiple deployments with different credentials
* Easy credential rotation via UI
* Secure encryption
* Multi-tenancy support

### Callback URL Security

Always use **HTTPS** in production:

* `https://yourapp.com/v1/integrations/oauth/callback`
* `http://yourapp.com/...` (insecure, OAuth will reject)

For local development:

* `http://localhost:3000/v1/integrations/oauth/callback`
* `http://127.0.0.1:3000/v1/integrations/oauth/callback`

### OAuth Scopes

We request the **minimum scopes** needed for each integration:

* GitHub: `repo`, `read:org`, `read:user`
* Google Workspace: `admin.directory.user.readonly`, etc.
* GCP: `cloud-platform` (required for Security Command Center - no read-only alternative available)

### User Data

We **never** store user passwords. OAuth flow:

1. User authorizes → Provider gives us an access token
2. We store the token (encrypted)
3. We use token to call APIs
4. User can revoke access anytime in the provider's settings

***

## Production Considerations

### Google OAuth Verification

If using Google integrations (Workspace, GCP) in production with external users, you'll need to submit your app for **Google's verification process**.

**Required for:**

* External user consent screen
* Requesting sensitive scopes (like `cloud-platform`)

**Process:**

1. Complete OAuth consent screen configuration
2. Submit for verification at [https://support.google.com/code/contact/oauth\_app\_verification](https://support.google.com/code/contact/oauth_app_verification)
3. Provide privacy policy, terms of service
4. May take 2-6 weeks

**For internal use:** No verification needed if using "Internal" consent screen.

### Rate Limiting

OAuth providers have rate limits. The integration platform handles this by:

* Caching API responses where appropriate
* Running checks via background jobs (Trigger.dev)
* Implementing exponential backoff on retries

### Token Refresh

OAuth tokens expire. The platform automatically:

* Stores refresh tokens (when provider supports it)
* Refreshes access tokens before they expire
* Re-prompts user to reconnect if refresh fails

No manual intervention needed!

***

## Summary

**Time investment:** \~30 minutes to configure all OAuth providers

**Benefit:** Users connect with 1 click instead of hunting for API keys

**Maintenance:** Minimal - credentials rotate via UI, no code deployments needed

**Security:** All credentials encrypted at rest, HTTPS required for callbacks

Configure once, benefit forever!


# Variables Reference
Source: https://www.trycomp.ai/docs/integrations/variables

Complete guide to user-configurable variables in checks

## Overview

Variables let users configure check behavior without changing code. For example:

* Which repositories to monitor
* Which teams to check
* Severity thresholds
* Include/exclude flags

## Variable Types

| Type | UI Component | Best For | Example |
| - | - | - | - |
| `text` | Text input | Free-form text | Organization ID, project name |
| `number` | Number input | Numeric values | Threshold, limit, count |
| `boolean` | Yes/No dropdown | Toggle flags | Include inactive, strict mode |
| `select` | Single dropdown | Choose one option | Environment, priority |
| `multi-select` | Multi-select dropdown | Choose multiple | Repositories, teams, users |

***

## Text Variables

**For:** Free-form text input (IDs, names, etc.)

```typescript theme={null}
{
  id: 'organization_id',
  label: 'Organization ID',
  type: 'text',
  required: true,
  placeholder: '123456789012',
  helpText: 'Your org ID from Settings → Organization',
  default: '', // Optional default value
}
```

**Access in check:**

```typescript theme={null}
const orgId = ctx.variables.organization_id as string;
```

***

## Number Variables

**For:** Numeric values (thresholds, limits, counts)

```typescript theme={null}
{
  id: 'max_days',
  label: 'Maximum Days',
  type: 'number',
  required: false,
  default: 90,
  placeholder: '90',
  helpText: 'Maximum age in days before flagging',
}
```

**Access in check:**

```typescript theme={null}
const maxDays = ctx.variables.max_days as number;
// or with default
const maxDays = (ctx.variables.max_days as number) || 90;
```

***

## Boolean Variables

**For:** Yes/No flags, enable/disable options

```typescript theme={null}
{
  id: 'include_inactive',
  label: 'Include Inactive Resources',
  type: 'boolean',
  required: false,
  default: false,
  helpText: 'Also check resources that are disabled',
}
```

**Renders as:** Dropdown with "Yes" / "No" options

**Access in check:**

```typescript theme={null}
const includeInactive = ctx.variables.include_inactive === true;
// or as string from select
const includeInactive = ctx.variables.include_inactive === 'true';
```

***

## Select Variables

**For:** Choose one option from a predefined list

### Static Options

```typescript theme={null}
{
  id: 'environment',
  label: 'Environment',
  type: 'select',
  required: true,
  default: 'production',
  options: [
    { value: 'production', label: 'Production' },
    { value: 'staging', label: 'Staging' },
    { value: 'development', label: 'Development' },
  ],
  helpText: 'Which environment to check',
}
```

### Dynamic Options (Fetched from API)

```typescript theme={null}
{
  id: 'project_id',
  label: 'Project',
  type: 'select',
  required: true,
  helpText: 'Select the project to monitor',

  fetchOptions: async (ctx) => {
    // Fetch projects from API
    const projects = await ctx.fetch<Project[]>('/projects');

    return projects.map((p) => ({
      value: p.id,
      label: p.name,
    }));
  },
}
```

**When dynamic options are used:**

1. User connects integration
2. Platform fetches options using the connection's credentials
3. User sees dropdown populated with real data from their account

**Access in check:**

```typescript theme={null}
const selectedEnv = ctx.variables.environment as string;
```

***

## Multi-Select Variables

**For:** Choose multiple items from a list (most common for selecting resources)

### Static Options

```typescript theme={null}
{
  id: 'alert_types',
  label: 'Alert Types to Monitor',
  type: 'multi-select',
  required: true,
  default: ['critical', 'high'],
  options: [
    { value: 'critical', label: 'Critical' },
    { value: 'high', label: 'High' },
    { value: 'medium', label: 'Medium' },
    { value: 'low', label: 'Low' },
  ],
}
```

### Dynamic Options (Most Common)

**Example:** Select which GitHub repositories to monitor

```typescript theme={null}
{
  id: 'target_repos',
  label: 'Repositories to Monitor',
  type: 'multi-select',
  required: true,
  helpText: 'Select repositories to check for compliance',

  fetchOptions: async (ctx) => {
    // Fetch all accessible repos
    const repos = await ctx.fetchAllPages<Repo>('/user/repos');

    return repos.map((r) => ({
      value: r.full_name,  // org/repo-name
      label: `${r.full_name}${r.private ? ' (private)' : ''}`,
    }));
  },
}
```

**Renders as:** Multi-select dropdown with search

**Access in check:**

```typescript theme={null}
const targetRepos = ctx.variables.target_repos as string[];

if (!targetRepos || targetRepos.length === 0) {
  ctx.fail({
    title: 'No Repositories Selected',
    description: 'Select at least one repository in integration settings',
    // ...
  });
  return;
}

// Only check selected repos
for (const repoName of targetRepos) {
  const repo = await ctx.fetch<Repo>(`/repos/${repoName}`);
  // Check the repo
}
```

***

## Default Values

```typescript theme={null}
{
  id: 'max_results',
  type: 'number',
  default: 100,  // Used if user doesn't configure
}

// In check
const maxResults = (ctx.variables.max_results as number) || 100;
```

**Use defaults for:**

* Optional settings with sensible defaults
* Advanced options most users don't change
* Don't use for required fields

***

## Required vs Optional Variables

### Required Variables

```typescript theme={null}
{
  id: 'organization_id',
  required: true,  // User MUST provide this
}
```

**Behavior:**

* User can't save without filling this
* Checks won't auto-run until provided
* Validation error shown if empty

**Use for:** Essential configuration (IDs, critical settings)

### Optional Variables

```typescript theme={null}
{
  id: 'include_archived',
  required: false,  // User can leave empty
  default: false,
}
```

**Behavior:**

* User can skip this
* Checks use default value if not set
* Checks auto-run even if not configured

**Use for:** Advanced settings, filters, optional features

***

## Variable Fetching Context

When using `fetchOptions`, you get a limited context:

```typescript theme={null}
fetchOptions: async (ctx) => {
  // Available:
  ctx.accessToken; // OAuth token
  ctx.fetch<T>(); // HTTP GET with auth
  ctx.fetchAllPages<T>(); // Paginated GET
  ctx.graphql<T>(); // GraphQL query

  // Not available:
  ctx.log(); // No logging during option fetch
  ctx.fail(); // Can't create findings
  ctx.variables; // No other variables (circular dependency)
};
```

**Keep it simple:**

* Fetch a list of resources
* Map to `{ value, label }` format
* Don't fetch large datasets (use pagination)
* Don't perform complex logic

***

## Validation

### In the Manifest

```typescript theme={null}
{
  id: 'api_url',
  type: 'url',  // Auto-validates URL format
  required: true,
}
```

**Built-in validation:**

* `required: true` - Can't be empty
* `type: 'url'` - Must be valid URL
* `type: 'number'` - Must be numeric

### In the Check

```typescript theme={null}
run: async (ctx) => {
  const orgId = ctx.variables.organization_id as string;

  if (!orgId || orgId.trim() === '') {
    ctx.fail({
      title: 'Organization ID Required',
      description: 'Configure the Organization ID in integration settings',
      resourceType: 'configuration',
      resourceId: 'organization_id',
      severity: 'critical',
      remediation: 'Go to Manage → Settings → Enter Organization ID',
      evidence: {},
    });
    return;
  }

  // Continue with check
};
```

***

## Reusable Variables

**Define once, use in multiple checks:**

```typescript theme={null}
// variables.ts
export const targetReposVariable: CheckVariable = {
  id: 'target_repos',
  label: 'Repositories to Monitor',
  type: 'multi-select',
  required: true,
  fetchOptions: async (ctx) => {
    // Fetch logic
  },
};

export const protectedBranchVariable: CheckVariable = {
  id: 'protected_branch',
  label: 'Branch to Check',
  type: 'text',
  required: true,
  default: 'main',
};
```

```typescript theme={null}
// checks/check-1.ts
import { targetReposVariable } from '../variables';

export const check1: IntegrationCheck = {
  variables: [targetReposVariable],
  // ...
};

// checks/check-2.ts
export const check2: IntegrationCheck = {
  variables: [targetReposVariable, protectedBranchVariable],
  // ...
};
```

**Benefits:**

* Consistent variable definitions
* Centralized option fetching
* Easier maintenance

***

## Auto-Run Behavior

**Checks auto-run after connection when:**

* All required variables are configured
* Connection is active
* Integration has checks defined

**Checks DON'T auto-run when:**

* Required variables are missing → User must configure them
* All variables are optional → Still auto-runs (uses defaults)

**After saving variables:**

* Platform checks if all required variables are now set
* If yes → Auto-triggers check run via Trigger.dev
* If no → Waits for remaining variables

***

## Best Practices

### Do's

* **Clear labels**: "Organization ID" not "Org ID" not "id"
* **Helpful help text**: Explain where to find the value
* **Good placeholders**: Show format/example
* **Sensible defaults**: For optional settings
* **Required only when truly needed**: Don't over-require

### Don'ts

* **Don't use vague labels**: "Setting 1"
* **Don't skip help text**: Users need guidance
* **Don't make everything required**: Only essentials
* **Don't fetch huge option lists**: Paginate or filter
* **Don't use technical jargon**: User-friendly language

***

## Examples from Built-in Integrations

### GitHub: Target Repositories

```typescript theme={null}
{
  id: 'target_repos',
  label: 'Repositories to Monitor',
  type: 'multi-select',
  required: true,
  fetchOptions: async (ctx) => {
    const orgs = await ctx.fetch<Org[]>('/user/orgs');
    const allRepos = [];
    for (const org of orgs) {
      const repos = await ctx.fetchAllPages<Repo>(`/orgs/${org.login}/repos`);
      allRepos.push(...repos.map(r => ({
        value: r.full_name,
        label: `${r.full_name}${r.private ? ' (private)' : ''}`,
      })));
    }
    return allRepos;
  },
}
```

### GCP: Organization ID

```typescript theme={null}
{
  id: 'organization_id',
  label: 'GCP Organization ID',
  type: 'text',
  required: true,
  placeholder: '123456789012',
  helpText: 'Numeric org ID from GCP Console → IAM & Admin → Settings',
}
```

### Linear: Target Teams

```typescript theme={null}
{
  id: 'target_teams',
  label: 'Teams to Monitor',
  type: 'multi-select',
  required: false, // Check all teams if not specified
  fetchOptions: async (ctx) => {
    const teams = await ctx.graphql<{ teams: { nodes: Team[] } }>(`
      query {
        teams {
          nodes {
            id
            name
            private
          }
        }
      }
    `);
    return teams.teams.nodes.map(t => ({
      value: t.id,
      label: `${t.name}${t.private ? ' (private)' : ''}`,
    }));
  },
}
```

***

## Summary

Variables make integrations flexible and user-friendly. Use them to:

* Let users scope checks to specific resources
* Configure thresholds and limits
* Enable/disable features
* Provide organization-specific context

**Keep it simple** - only add variables when truly needed for configuration.


# Writing Integrations
Source: https://www.trycomp.ai/docs/integrations/writing-integrations

Step-by-step guide to creating integration manifests and checks

## Prerequisites

* TypeScript knowledge
* Understanding of the service you're integrating
* API documentation for the service

## Step 1: Create Integration Folder

Create a new folder in `packages/integration-platform/src/manifests/`:

```bash theme={null}
mkdir -p packages/integration-platform/src/manifests/your-service
cd packages/integration-platform/src/manifests/your-service
```

**File structure:**

```
your-service/
├── index.ts           # Manifest definition
├── types.ts           # TypeScript types
├── checks/
│   ├── index.ts       # Export all checks
│   └── your-check.ts  # Individual checks
└── helpers/           # Optional: API client helpers
    └── api-client.ts
```

## Step 2: Define Types

Create `types.ts` for the integration's data structures:

```typescript theme={null}
// Service-specific types
export interface YourServiceUser {
  id: string;
  email: string;
  twoFactorEnabled: boolean;
}

export interface YourServiceCredentials {
  access_token?: string; // For OAuth
  api_key?: string;      // For API key auth
}
```

## Step 3: Create the Manifest

Create `index.ts`:

```typescript theme={null}
import type { IntegrationManifest } from '../../types';
import { yourCheck } from './checks';

export const yourServiceManifest: IntegrationManifest = {
  id: 'your-service',
  name: 'Your Service',
  description: 'Monitor compliance in Your Service',
  category: 'Developer Tools',
  logoUrl: 'https://img.logo.dev/yourservice.com?token=pk_TOKEN',
  docsUrl: 'https://docs.yourservice.com/api',
  isActive: true,

  auth: {
    type: 'oauth2',
    config: {
      authorizeUrl: 'https://yourservice.com/oauth/authorize',
      tokenUrl: 'https://yourservice.com/oauth/token',
      scopes: ['read:users', 'read:security'],
      pkce: false,
      clientAuthMethod: 'body',
      supportsRefreshToken: true,
      authorizationParams: {
        access_type: 'offline',
      },
      setupInstructions: `Create an OAuth app at https://yourservice.com/apps`,
      createAppUrl: 'https://yourservice.com/apps/new',
    },
  },

  baseUrl: 'https://api.yourservice.com',
  defaultHeaders: {
    'Content-Type': 'application/json',
  },

  capabilities: ['checks'],

  checks: [yourCheck],
};
```

## Step 4: Write a Check

Create `checks/your-check.ts`:

```typescript theme={null}
import type { CheckContext, IntegrationCheck } from '../../../types';
import { TASK_TEMPLATES } from '../../../task-mappings';
import type { YourServiceUser } from '../types';

export const twoFactorCheck: IntegrationCheck = {
  id: 'two-factor-auth',
  name: '2FA Enabled',
  description: 'Verify all users have 2FA enabled',
  taskMapping: TASK_TEMPLATES['2fa'],
  defaultSeverity: 'high',
  variables: [],

  run: async (ctx: CheckContext) => {
    ctx.log('Checking 2FA status for all users');

    // Fetch users from API
    const users = await ctx.fetch<YourServiceUser[]>('/users');

    ctx.log(`Found ${users.length} users`);

    // Check each user
    for (const user of users) {
      if (!user.twoFactorEnabled) {
        ctx.fail({
          title: `2FA Disabled for ${user.email}`,
          resourceType: 'user',
          resourceId: user.id,
          severity: 'high',
          description: `User ${user.email} does not have 2FA enabled`,
          remediation: 'Enable 2FA in account settings',
          evidence: {
            userId: user.id,
            email: user.email,
            twoFactorEnabled: false,
          },
        });
      }
    }

    const usersWithout2FA = users.filter((u) => !u.twoFactorEnabled).length;

    if (usersWithout2FA === 0) {
      ctx.pass({
        title: 'All Users Have 2FA',
        resourceType: 'users',
        resourceId: 'all',
        description: `All ${users.length} users have 2FA enabled`,
        evidence: { totalUsers: users.length },
      });
    }

    ctx.log(`Check complete: ${usersWithout2FA} users without 2FA`);
  },
};
```

## Step 5: Add Variables (Optional)

If your check needs user configuration:

```typescript theme={null}
const targetReposVariable: CheckVariable = {
  id: 'target_repos',
  label: 'Repositories to Monitor',
  type: 'multi-select',
  required: true,
  helpText: 'Select which repositories to check',
  
  // Dynamic options from API
  fetchOptions: async (ctx) => {
    const repos = await ctx.fetch<Repo[]>('/repos');
    return repos.map((r) => ({
      value: r.name,
      label: r.full_name,
    }));
  },
};

export const yourCheck: IntegrationCheck = {
  id: 'repo-check',
  variables: [targetReposVariable],
  
  run: async (ctx) => {
    const targetRepos = ctx.variables.target_repos as string[];
    // Only check selected repos
  },
};
```

## Step 6: Register the Manifest

Add to `packages/integration-platform/src/registry/index.ts`:

```typescript theme={null}
import { yourServiceManifest } from '../manifests/your-service';

export const registry: IntegrationRegistry = {
  // ... existing integrations
  'your-service': yourServiceManifest,
};
```

## Step 7: Test It

1. **Start dev servers:**
   ```bash theme={null}
   bun run dev
   ```

2. **Configure OAuth** (if using OAuth):
   * Go to `/admin/integrations`
   * Find your integration → Configure OAuth
   * Add Client ID/Secret

3. **Connect the integration:**
   * Go to `/integrations`
   * Find your integration
   * Click "Connect"
   * Authorize (if OAuth) or enter credentials

4. **Run checks:**
   * Go to `/cloud-tests` (if it's a cloud provider)
   * Or go to a task page and run the integration check
   * Verify findings appear correctly

5. **Check logs:**
   * Look at API terminal for check execution logs
   * Verify no errors

## Common Patterns

### Pagination

```typescript theme={null}
// Auto-pagination (OAuth with standardized pagination)
const allItems = await ctx.fetchAllPages<Item>('/items');

// Manual pagination
let items: Item[] = [];
let page = 1;

while (true) {
  const response = await ctx.fetch<{ data: Item[]; hasMore: boolean }>(
    `/items?page=${page}`
  );
  items.push(...response.data);
  if (!response.hasMore) break;
  page++;
}
```

### Error Handling

```typescript theme={null}
try {
  const data = await ctx.fetch('/endpoint');
  // Process data
} catch (error) {
  const errorMessage = error instanceof Error ? error.message : String(error);
  
  // Handle specific errors
  if (errorMessage.includes('PERMISSION_DENIED')) {
    ctx.fail({
      title: 'Permission Denied',
      resourceType: 'api',
      resourceId: 'access',
      severity: 'high',
      description: 'Your account lacks necessary permissions',
      remediation: 'Grant [specific role] in provider settings',
      evidence: { error: errorMessage },
    });
    return;
  }
  
  // Generic error
  ctx.log(`Error: ${errorMessage}`);
}
```

### Multiple Checks

```typescript theme={null}
// checks/index.ts
export { check1 } from './check-1';
export { check2 } from './check-2';
export { check3 } from './check-3';

// index.ts
import { check1, check2, check3 } from './checks';

export const manifest: IntegrationManifest = {
  // ...
  checks: [check1, check2, check3],
};
```

## Best Practices

### Do's

* **Use descriptive IDs**: `branch-protection`, not `check1`
* **Map to tasks**: Use `taskMapping` to auto-complete tasks
* **Friendly errors**: Convert API errors to user-friendly messages
* **Log liberally**: Use `ctx.log()` for debugging
* **Handle missing data**: Not all orgs have all resources
* **Paginate when needed**: Don't assume small datasets
* **Type everything**: Use TypeScript types for API responses

### Don'ts

* **Don't expose raw API errors** to users in descriptions
* **Don't assume variables exist**: Check for undefined
* **Don't use `console.log`**: Use `ctx.log()` instead
* **Don't create findings for missing resources**: Just log it
* **Don't hardcode URLs**: Use `baseUrl` in manifest
* **Don't skip error handling**: Wrap API calls in try/catch

## Examples to Reference

| Integration | Type | Good for learning |
| - | - | - |
| **GitHub** | OAuth | Dynamic variables, pagination, multiple checks |
| **Google Workspace** | OAuth | User iteration, domain-scoped checks |
| **AWS** | Custom | Complex credentials, error handling |
| **Azure** | Custom | Multi-field credentials, API error mapping |
| **Linear** | OAuth | Simple OAuth, GraphQL |
| **Vercel** | OAuth | Project scoping, deployment checks |

All integration source code is in `packages/integration-platform/src/manifests/`.

## Need Help?

* Check existing integration manifests for patterns
* Review type definitions in `src/types.ts`
* See the [Contributing Guide](/docs/integrations/contributing) for PR requirements


# Welcome to Comp AI
Source: https://www.trycomp.ai/docs/introduction

Comp AI documentation for compliance automation, evidence collection, policies, integrations, Trust Centers, device compliance, and the public API.

Comp AI is an AI-first compliance platform for teams building and maintaining SOC 2, ISO 27001, HIPAA, GDPR, and customer security programs.

Use these docs to configure automated evidence collection, policy workflows, cloud checks, integrations, device compliance, security questionnaires, Trust Access, and API-driven compliance automation.

## Start Here

> **[Automated evidence](/docs/automated-evidence)**
>
> Collect recurring proof from connected systems and keep compliance tasks current.

> **[Security questionnaires](/docs/security-questionnaire)**
>
> Generate questionnaire answers from approved policies, knowledge base documents, and organization
> context.

> **[Trust Access](/docs/trust-access)**
>
> Manage external access requests, NDAs, grants, and shared Trust Center resources.

> **[Cloud tests](/docs/cloud-tests)**
>
> Connect AWS, Azure, and GCP to monitor cloud posture and collect security evidence.

## Build With Comp AI

> **[MCP Connector](/docs/mcp-connector)**
>
> Drive your compliance program from Claude, Cursor, ChatGPT, and other AI assistants — one URL and a sign-in, no install or API key.

> **[Compliance Automation API](/docs/api-reference/overview)**
>
> Automate evidence, policies, tasks, Trust Access, security questionnaires, and compliance workflows with the Comp AI API.

> **[Integrations](/docs/integrations)**
>
> Build and configure integrations that sync data, run checks, and produce compliance evidence.


# MCP Connector
Source: https://www.trycomp.ai/docs/mcp-connector

Connect any AI assistant to Comp AI with one URL and a sign-in — no install, no API key. The hosted, recommended way to use the Comp AI MCP.

The Comp AI **MCP Connector** is our hosted MCP server at `mcp.trycomp.ai`. You connect an AI assistant — Claude, Cursor, ChatGPT, VS Code — by pasting **one URL** and signing in. There is nothing to install and no API key to manage: access is granted through OAuth, scoped to your own Comp AI permissions, and revocable at any time.

> This is the recommended way to connect. The self-managed [MCP Server](/docs/mcp-server) — run locally from an API key via `npx` — is deprecated; existing installs keep working, but new setups should stay on this page.

## Why the connector

> **Nothing to install**
>
> No npm package, no config file. Paste a URL; the assistant handles the rest.

> **Sign in, don't copy a key**
>
> OAuth in your browser. No API key to generate, paste, or rotate.

> **Your own permissions**
>
> The connection can only do what your Comp AI role can do — per user, not a shared key.

> **Revoke in one click**
>
> Turn off a connection from Settings whenever you want; it stops working immediately.

## The one thing you need

```
https://mcp.trycomp.ai/mcp
```

Paste that into any client's custom / remote MCP connector setup. Everything else — discovery, sign-in, approval — happens automatically.

> [!NOTE]
>
> The assistant connects to `mcp.trycomp.ai` from the vendor's cloud (this is true even for desktop apps), so nothing runs on your machine and the server must simply be reachable over the internet — which it is.

## Connect your assistant

**Claude (Desktop & web)**

Custom connectors work on Free, Pro, Max, Team, and Enterprise plans.

**1. Open connector settings**

Go to **Customize → Connectors**.

**2. Add a custom connector**

Click **“+” → Add custom connector**, then enter:

* **Name:** `Comp AI`
* **URL:** `https://mcp.trycomp.ai/mcp`

Click **Add**. Leave *Advanced settings* empty — no client ID or secret is needed.

**3. Sign in**

Follow the sign-in and approval screen (see [What approval looks like](#what-approval-looks-like)).

**4. Enable it in a chat**

In a conversation, click the **“+”** button, choose **Connectors**, and enable **Comp AI**.

On **Team / Enterprise**, an organization Owner adds it once under **Organization settings → Connectors → Add → Custom → Web**; members then **Connect** it from **Customize → Connectors**.

**Claude Code (CLI)**

```bash theme={null}
claude mcp add --transport http comp-ai https://mcp.trycomp.ai/mcp
```

Then start (or restart) Claude Code and run:

```
/mcp
```

Select **comp-ai** and complete the browser sign-in. That's it — no API key.

**Other clients**

Any assistant that supports a **remote / custom MCP connector over HTTP** works the same way — there is nothing Comp AI-specific to install. Add a custom connector and paste:

```
https://mcp.trycomp.ai/mcp
```

For the exact menu path, follow your client's own connector guide:

* **Cursor** — Settings → MCP / Connectors → add a remote server
* **ChatGPT** — Settings → Connectors → add a custom connector (availability varies by plan)
* **VS Code** — the MCP: Add Server command, choosing an HTTP server

If your client can't use a remote connector, call the [Comp AI API](/docs/api-reference/overview) directly. The self-managed [MCP Server](/docs/mcp-server) is deprecated.

## What approval looks like

The first time you connect, you'll see an approval screen. It's built to make one thing obvious: **where your access is going.**

* **The destination host is shown large** — for the real connector it reads `mcp.trycomp.ai`. This is the field that matters; an app's *name* is chosen by whoever registered it, so the host is what to check.
* **Choose your organization.** If you belong to more than one, pick which one the connection acts on. (You can change it later in Settings.)
* **Tick to acknowledge**, then **Allow access**. The grant matches your own permissions — there is no read-only mode.

> [!NOTE]
>
> You may see “Comp AI has not reviewed this app.” That's expected for connectors we haven't formally vetted, and it isn't a failure — only continue if you started the connection yourself.

## Manage or disconnect

Open **Settings → your profile → Connected apps**. Each connected assistant is listed with the host it sends tokens to and a **Revoke** button. Revoking deletes the grant and its tokens, so that assistant stops working immediately — reconnect from the assistant to use it again.

## Connector vs. self-managed

> **MCP Connector (this page)**
>
> Hosted by Comp AI. One URL, OAuth sign-in, per-user permissions, revoke in Settings. Best for people using an AI assistant day to day.

> **[MCP Server, self-managed (deprecated)](/docs/mcp-server)**
>
> Runs locally from a Comp AI API key via `npx`. Deprecated — kept working for existing installs only; new setups should use the connector or the API.

## Resources

* [Model Context Protocol](https://modelcontextprotocol.io/) — the open standard this is built on
* [MCP Server](/docs/mcp-server) — the deprecated self-managed, API-key option


# MCP Server (Deprecated)
Source: https://www.trycomp.ai/docs/mcp-server

Deprecated: running the Comp AI MCP server locally from an API key via npx. New setups should use the hosted MCP Connector.

> [!WARNING]
>
> **The self-managed MCP server is deprecated.** New setups should use the [**MCP Connector**](/docs/mcp-connector) — one URL and a sign-in, with nothing to install and no API key to manage. Existing `npx` installs keep working for now; this page remains as their reference.

The Comp AI MCP server lets you and your team operate your entire compliance program from inside any modern AI assistant. Ask in plain language; the AI uses real Comp AI tools to read evidence, manage tasks, generate questionnaire answers, connect cloud accounts, and more — all under your existing API key and permissions.

> Built on the [Model Context Protocol](https://modelcontextprotocol.io/) — an open standard that lets AI clients talk to external tools. The Comp AI MCP server publishes hundreds of tools spanning evidence, policies, integrations, frameworks, cloud security, vendors, risks, people, and tasks.

## Why use it

Compliance work is full of repetitive, multi-step actions: gathering evidence, answering questionnaires, reviewing tasks, connecting cloud accounts. The MCP server collapses those into one-line natural-language requests. Examples your team can run today:

* *"Show me my open SOC 2 controls and tell me which ones are missing evidence."*
* *"Upload this vendor security questionnaire and generate the answers from our policies."*
* *"Connect our production AWS account for monitoring."*
* *"List employees who haven't completed offboarding yet."*
* *"Mark the AWS audit task on Sarah's account as done."*
* *"Export our SOC 2 evidence bundle for the upcoming audit."*

The AI assistant figures out which tools to call. Your team types the request and reviews the result.

## Get an API key

1. Sign in to [Comp AI](https://app.trycomp.ai).
2. Open **Settings → API Keys**.
3. Click **Create new key**. Scope it to the actions the AI assistant should be allowed to take.
4. Copy the key (it starts with `comp_`) — you will paste it into your AI client's config once. Copy the full string exactly, with no extra characters, spaces, or line breaks.

The API key carries your existing RBAC and permissions. The AI assistant can only do what *your* role can do in the dashboard.

## Install per AI client

You don't manually download anything. The Comp AI MCP server is distributed as a public npm package — [`@trycompai/mcp-server`](https://www.npmjs.com/package/@trycompai/mcp-server) — and every install path below uses `npx -y` (or a one-click button / drag-and-drop bundle) to fetch it on demand the first time your AI client starts a session. New versions are picked up automatically on the next session.

Pick the tab for your client. Each tab shows the easiest install path first, with a manual JSON option below for advanced setups.

> [!NOTE]
>
> The `npx -y @trycompai/mcp-server` command you'll see throughout is what handles the download. Your AI client runs it in the background when you start a chat; npm fetches the latest published version from [npmjs.com](https://www.npmjs.com/package/@trycompai/mcp-server) and caches it locally. Nothing for you to install manually.

**Claude Desktop**

**Easiest path — drag-and-drop install:**

> **[Download for Claude Desktop](https://api.trycomp.ai/mcp/download/claude-desktop)**
>
> Always serves the latest Comp AI MCP bundle (`.mcpb`) — no version hunting.

1. Click **Download for Claude Desktop** above to get the latest `mcp-server.mcpb` bundle.
2. Drag the downloaded `.mcpb` file directly onto the Claude Desktop window.
3. Claude Desktop shows an install prompt — confirm, then paste your Comp AI API key in the extension settings.
4. Restart any open chats. Comp AI tools are now available.

No JSON editing required.

> **Advanced — manual JSON config**
>
> If you prefer to manage `claude_desktop_config.json` yourself, open **Settings → Developer → Edit Config** and merge:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "comp-ai": {
>       "command": "npx",
>       "args": [
>         "-y",
>         "@trycompai/mcp-server",
>         "start",
>         "--apikey",
>         "comp_your_api_key_here"
>       ]
>     }
>   }
> }
> ```
>
> Fully quit and reopen Claude Desktop.

**Cursor**

**Easiest path — one-click install:**

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=CompAi\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAdHJ5Y29tcGFpL21jcC1zZXJ2ZXIiLCJzdGFydCIsIi0tYXBpa2V5IiwiIl19)

Click the button above, confirm in Cursor, then paste your Comp AI API key when prompted.

> **Advanced — manual JSON config**
>
> Open **Cursor → Settings → Tools and Integrations → New MCP Server** and paste:
>
> ```json theme={null}
> {
>   "command": "npx",
>   "args": [
>     "-y",
>     "@trycompai/mcp-server",
>     "start",
>     "--apikey",
>     "comp_your_api_key_here"
>   ]
> }
> ```
>
> Save and reload Cursor.

**VS Code**

**Easiest path — one-click install:**

[![Install in VS Code](https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square\&label=Install%20CompAi%20MCP\&color=0098FF)](vscode://ms-vscode.vscode-mcp/install?name=CompAi\&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAdHJ5Y29tcGFpL21jcC1zZXJ2ZXIiLCJzdGFydCIsIi0tYXBpa2V5IiwiIl19)

Click the button above, confirm in VS Code, then paste your Comp AI API key when prompted.

> **Advanced — manual JSON config**
>
> Open the **Command Palette → MCP: Open User Configuration** and paste:
>
> ```json theme={null}
> {
>   "command": "npx",
>   "args": [
>     "-y",
>     "@trycompai/mcp-server",
>     "start",
>     "--apikey",
>     "comp_your_api_key_here"
>   ]
> }
> ```

**Claude Code (CLI)**

Install with one command:

```bash theme={null}
claude mcp add CompAI -- npx -y @trycompai/mcp-server start --apikey comp_your_api_key_here
```

Claude Code registers the server immediately — Comp AI tools become available in your next session.

**Codex CLI**

Install with one command:

```bash theme={null}
codex mcp add comp-ai -- npx -y @trycompai/mcp-server start --apikey comp_your_api_key_here
```

Codex registers the server immediately — Comp AI tools become available in your next session.

For ChatGPT desktop / web with MCP support, follow OpenAI's MCP integration docs and use the same `command` + `args` shape shown in the manual JSON sections of the other tabs.

**Gemini CLI**

Install with one command:

```bash theme={null}
gemini mcp add CompAI -- npx -y @trycompai/mcp-server start --apikey comp_your_api_key_here
```

**Windsurf**

Open **Windsurf → Settings → Cascade → Manage MCPs → View raw config** and paste:

```json theme={null}
{
  "mcpServers": {
    "comp-ai": {
      "command": "npx",
      "args": [
        "-y",
        "@trycompai/mcp-server",
        "start",
        "--apikey",
        "comp_your_api_key_here"
      ]
    }
  }
}
```

Save and reload Windsurf.

That's it. The first time you start a chat in your AI client after install, the assistant will discover the Comp AI tools and start using them.

## Verify it worked

Open a fresh chat in your AI client and ask:

> *"List my open compliance tasks."*

If the install succeeded, the AI will call Comp AI's `list-tasks` tool and return tasks from your organization. If you see no tool calls or an authentication error, jump to **Troubleshooting** below.

## Troubleshooting

> **The AI says it doesn't have Comp AI tools available**
>
> Most common causes:
>
> * You didn't fully quit and reopen your AI client after the install. Closing the window isn't enough — quit it from the menu / dock and reopen.
> * The JSON config has a syntax error. Mintlify can validate this if you paste it into any JSON linter.
> * For Claude Desktop: confirm `claude_desktop_config.json` was saved to the right path: `~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows.

> **401 / authentication error**
>
> * Confirm your API key starts with `comp_` and you copied the full string (these keys are long).
> * Confirm the key hasn't been revoked in **Comp AI → Settings → API Keys**.
> * Confirm the key's role has permission for the action you're asking the AI to take.

> **Every tool call fails with an encoding error (e.g. “character … value 8230”)**
>
> This means the API key in your config contains a stray non-standard character — most often an ellipsis (`…`) accidentally pasted in place of the real key. HTTP headers only allow plain characters, so the request can't be sent.
>
> Fix it by re-entering the key cleanly:
>
> 1. In **Comp AI → Settings → API Keys**, copy your key again (or create a new one).
> 2. In your config, replace the entire `--apikey` value so it's just your real key — `comp_` followed by letters and numbers, with **no `…`, spaces, or line breaks**.
> 3. Fully quit and reopen your AI client.

> **`npx` or `command not found`**
>
> The MCP server runs via [npm](https://npmjs.com) + [Node.js](https://nodejs.org). If your machine doesn't have Node 18+ installed, install it from [nodejs.org](https://nodejs.org/) and restart your AI client.

> **Tools show up but actions fail**
>
> Open Chrome / Safari DevTools (or your client's debug log) and inspect the network response. Common causes:
>
> * Your role lacks the permission for that endpoint (RBAC enforced server-side).
> * You're on a custom plan that doesn't include the feature being called.
> * The Comp AI API is briefly unavailable — try again in a moment or check status.

## What your AI assistant can do

The MCP server publishes tools across the Comp AI surface:

| Area | Examples |
| - | - |
| **Evidence and tasks** | List tasks, upload evidence, complete checklist items, export audit bundles |
| **Policies** | List policies, generate drafts, publish versions, attach PDFs |
| **Security questionnaires** | Upload, parse questions, generate answers, export reviewer-ready files |
| **Frameworks and controls** | Inspect SOC 2 / ISO 27001 / HIPAA / GDPR coverage and missing evidence |
| **Integrations and cloud security** | Connect AWS, Azure, GCP and other providers; run checks; review findings |
| **Vendors and risks** | List vendors, manage assessments, track risk and remediation |
| **People and devices** | Invite members, manage offboarding, inspect device compliance |
| **Trust Center** | Review and approve Trust Access requests, manage shared documents |

Some endpoints are intentionally **not** exposed to AI clients for security or compatibility reasons — for example, anything that rotates raw credentials, and a small number of long-lived streaming endpoints that don't fit the request/response shape AI clients expect. The web UI continues to support those flows directly.

## Common workflows

> **[Generate questionnaire answers](/docs/security-questionnaire)**
>
> Ask your AI to upload a vendor questionnaire and produce answers grounded in your policies.

> **[Connect a cloud account](/docs/cloud-tests)**
>
> Ask the AI to connect AWS, Azure, or GCP — you provide the auditor role ARN; the AI handles the rest.

> **[Run integration checks](/docs/integrations)**
>
> Trigger and inspect compliance checks across your connected providers in plain language.

> **[Manage tasks and evidence](/docs/automated-evidence)**
>
> Pull open tasks, attach evidence, and mark items complete from inside your AI assistant.

## Security

* **Your API key, your scope.** The MCP server runs locally on your machine and authenticates to the Comp AI API using the key you paste. It carries the same permissions you configured for that key — no escalation.
* **Multi-tenant safety.** Every request is scoped to the organization the API key belongs to. The AI cannot read or modify data belonging to other Comp AI organizations.
* **Secrets stay on your machine.** Your API key lives in your AI client's local config file. It is never sent to Comp AI, npm, or any third party except your own AI client's vendor.
* **Sensitive endpoints are hidden.** Endpoints that handle raw secrets (credential rotation, vault material) are deliberately excluded from the MCP tool surface. They remain available in the Comp AI web UI for human operators only.
* **All actions are logged.** Mutations performed through the MCP server appear in your Comp AI audit log marked with API-key authentication, so you can review who did what.

## When to use the MCP server vs the API

| If you want to… | Use |
| - | - |
| Operate your compliance program day-to-day with help from an AI assistant | **[MCP Connector](/docs/mcp-connector)** |
| Build a custom internal tool, dashboard, or one-off automation | **[Comp AI API](/docs/api-reference/overview)** directly |
| Pipe Comp AI data into your data warehouse on a schedule | **API** directly |
| Onboard a new auditor or external reviewer to your Trust Center | **Comp AI web UI** |

The MCP server and the public API hit the same endpoints with the same RBAC — the only difference is the consumer (an AI assistant vs your own code).

## FAQ

> **Do I need to host the MCP server?**
>
> No — and new setups no longer run it locally either. The hosted [MCP Connector](/docs/mcp-connector) is the supported path: Comp AI runs it, and you connect with one URL and a sign-in. This deprecated self-managed option runs on each user's machine via `npx` and needs no infrastructure of your own.

> **Does the MCP server work offline?**
>
> No. The server is a thin translator between your AI client and the Comp AI API at `https://api.trycomp.ai`. An internet connection is required.

> **Can multiple teammates use it at the same time?**
>
> Yes. Each teammate installs the MCP server on their own machine with their own Comp AI API key. Their actions are independently authenticated and audit-logged.

> **What if my AI client doesn't support MCP yet?**
>
> You can still use the [Comp AI API](/docs/api-reference/overview) directly. The MCP server is an additional way to interact with the same endpoints — it doesn't replace anything.

> **How do new features show up?**
>
> New tools and improvements ship with each Comp AI release. Because `npx -y` always pulls the latest published version, your AI client picks up new tools automatically the next time it starts the MCP server.

> **Where can I report an issue?**
>
> Open an issue at [github.com/trycompai/comp/issues](https://github.com/trycompai/comp/issues) or email [hello@trycomp.ai](mailto:hello@trycomp.ai).

## Resources

* **npm package:** [`@trycompai/mcp-server`](https://www.npmjs.com/package/@trycompai/mcp-server)
* **Source:** [github.com/trycompai/comp](https://github.com/trycompai/comp/tree/main/apps/mcp-server)
* **Direct API reference:** [Comp AI API](/docs/api-reference/overview)
* **Model Context Protocol overview:** [modelcontextprotocol.io](https://modelcontextprotocol.io/)


# Penetration Tests
Source: https://www.trycomp.ai/docs/penetration-tests

Create AI-assisted penetration test runs, track security findings, and download Markdown or PDF report deliverables.

## About Penetration Tests

Penetration Tests lets your team run one-time external security assessments and receive a generated report with findings and remediation guidance.

The feature is available in **Security** as **Penetration Tests**.

### What you can do

* Start a new one-time penetration test from a target URL
* Track queued and in-progress jobs in a single list view
* Open run details for status and execution metadata
* Triage each finding, including disputing findings you believe are wrong
* Download report artifacts when complete (Markdown and PDF)

## Prerequisites

Before using Penetration Tests, make sure:

1. Your organization has the feature enabled
2. You have access to the **Security** section
3. You know the target URL you want tested

## Create a penetration test

1. Go to **Security** → **Penetration Tests**
2. Click **Create Report**
3. Enter a **Target URL**
4. (Optional) Enter a repository URL for additional context
5. Continue through checkout to queue the run

> [!NOTE]
>
> If you enter a domain without a protocol (for example `example.com`), Comp will normalize it to a
> valid URL format.

## Track run status

After submission, the run appears in your report list and detail page.

Common states include:

* **In queue**: Job accepted and waiting to start
* **Running**: Assessment is in progress
* **Completed**: Artifacts are ready
* **Failed/Cancelled**: Run did not complete successfully

For in-progress runs, the detail page shows live progress information when available.

## Review and dispute findings

Each finding in a completed run has a status you can change from the finding's
detail page:

| Status | Use it when |
| - | - |
| **Open** | Not yet triaged. This is the starting state. |
| **Acknowledged** | The finding is valid and you've accepted it into your remediation queue. |
| **Resolved** | You've fixed the underlying issue. |
| **False positive** | The finding is wrong — the reported issue isn't actually present or isn't exploitable as described. |
| **Won't fix** | The finding is real, but you're accepting the risk rather than remediating it. |

**False positive** and **Won't fix** dispute the finding, and both require a
written justification.

1. Open **Security** → **Penetration Tests** and select a completed run
2. Select the finding you want to dispute
3. Click **Dispute finding**
4. Choose your position — *It isn't a real vulnerability* (marks it False
   positive) or *It's real, but we're not fixing it* (marks it Won't fix)
5. Write your reason — be specific about *why* the finding doesn't apply. The
   progress bar fills as you type and reads **Ready to submit** once the reason
   is long enough
6. Click **Submit dispute**

If you agree with a finding instead, use **Acknowledge** (real, queued for
remediation) or **Mark resolved** (fixed). Neither requires a written reason,
and both save immediately.

> [!NOTE]
>
> The justification is required. Comp will not accept a dispute without one, because a dismissed
> finding with no recorded reason is not defensible in an audit.

### What happens to a disputed finding

* It **stays visible** in the findings list, marked with its status and dimmed — disputing a finding never hides it
* It is **excluded from the headline severity counts**, so your critical/high totals reflect findings you still consider real. **Resolved** findings are excluded too; **Acknowledged** ones are still counted, because acknowledging a finding doesn't fix it
* You can **Reopen** it at any time, which puts it back in the counts
* The justification is written to your **audit log**, with the user who made the change and when
* The justification is added to the finding's **status history**, so the full triage trail is preserved
* The justification is shared with the testing agent on **future scans of the same target**, so a retest evaluates the finding with your context instead of blindly re-reporting it

> [!WARNING]
>
> Disputing a finding is an auditable action. Comp AI records every status change, who made it,
> and the reason given. Write justifications you'd be comfortable defending in an audit.

### Who can dispute a finding

Changing a finding's status requires the `pentest:update` permission — held by
**owners** and **admins** by default.

The built-in **Auditor** role has no access to penetration tests. To share
results with an auditor, download the PDF report from the run detail page.

## Access deliverables

When a run completes, open the run detail page to access:

* **View markdown**: Opens the generated report content
* **Download PDF**: Downloads a customer-shareable report artifact

## Best practices

1. Start with externally reachable staging or production-like targets
2. Run tests after major infrastructure or application changes
3. Review findings with engineering and assign remediation owners
4. Triage every finding rather than leaving it Open — an untriaged backlog is hard to defend in an audit
5. Write disputes that explain *why* the finding doesn't apply, not just that it doesn't. "Internal-only endpoint, not routable from the internet" is defensible; "not applicable" is not
6. Keep completed PDFs for audit and customer security reviews

## Troubleshooting

> **I do not see the Penetration Tests tab**
>
> Feature access and visibility
>
> Verify your organization has the feature enabled and that your user has access to Security pages.

> **My run is stuck in queue or progress is delayed**
>
> Status updates and provider execution
>
> Refresh the page and check the run detail view. If status does not change after a reasonable
> period, contact support with the run ID.

> **Report download is unavailable**
>
> Artifact availability
>
> PDF and markdown artifacts are available after the run reaches Completed status.

> **I can't change a finding's status**
>
> Permissions on finding triage
>
> Changing a finding status requires the `pentest:update` permission. Ask an owner or admin in
> your organization to make the change.

> **My dispute was rejected because the reason was too short**
>
> Justification requirements
>
> **False positive** and **Won't fix** require a written justification of at least 20 characters.
> Explain why the finding doesn't apply to your environment — this text is what an auditor reads
> when reviewing the dismissal.

> **A finding I marked as a false positive came back on the next scan**
>
> Retest behavior
>
> Your justification is shared with the testing agent on future scans of the same target, but it
> does not permanently suppress the finding — the agent re-evaluates it with your context. If it
> reappears, the agent found evidence the issue is reachable. Review the new finding's proof of
> concept before dismissing it again.

## Support

If you need help with Penetration Tests:

1. Contact support at [support@trycomp.ai](mailto:support@trycomp.ai)
2. Join our [Discord community](https://discord.gg/compai)


# Security Questionnaire
Source: https://www.trycomp.ai/docs/security-questionnaire

Automatically answer vendor security questionnaires with approved policies, knowledge base documents, and Comp AI review workflows.

> [!NOTE]
>
> For server-side automation, use the API-key protected questionnaire endpoints in the [API
> reference](/docs/api-reference/questionnaire/upload-a-questionnaire-file-and-auto-answer-with-export).

### About Security Questionnaire

The Security Questionnaire feature allows you to automatically analyze and answer vendor security questionnaires using AI. Upload questionnaires from vendors, and our system will extract questions and generate answers based on your organization's published policies and documentation.

**Key Benefits:**

* **Automated Question Extraction**: Upload questionnaire files and let AI extract all questions automatically
* **Intelligent Answer Generation**: Answers are generated based on your published policies and organizational context
* **Manual Review & Editing**: Review and edit answers before exporting
* **Knowledge Base Integration**: Leverage your organization's knowledge base for comprehensive answers

### Prerequisites

Before using the Security Questionnaire feature, ensure you have:

1. **Published Policies**: You must have at least one published policy in your organization
   * Navigate to **Policies** → **All Policies** to publish policies
   * Published policies are used as the source of truth for generating answers

> [!NOTE]
>
> If you don't have published policies, you'll see an onboarding screen prompting you to publish
> policies first.

### Getting Started

#### Step 1: Access Security Questionnaire

1. Navigate to **Security Questionnaire** in your organization dashboard
2. You'll see the overview page with:
   * A "Create New Questionnaire" card
   * History of previously parsed questionnaires

#### Step 2: Create a New Questionnaire

1. Click the **New Questionnaire** button
2. Upload your questionnaire file (PDF, DOCX, or other supported formats)
3. The system will automatically:
   * Extract questions from the document
   * Generate answers based on your published policies
   * Create a structured questionnaire view

#### Step 3: Review and Edit Answers

Once the questionnaire is parsed:

* **View Questions**: Browse through all extracted questions
* **Review Answers**: Check AI-generated answers for accuracy
* **Edit Answers**: Click on any answer to edit it manually
* **Add Context**: Link answers to specific knowledge base documents or policies
* **Manual Answers**: Add manual answers for questions that require custom responses

#### Step 4: Export Questionnaire

After reviewing and editing:

1. Click **Export** to generate the completed questionnaire
2. The exported file will include all your answers ready for submission

### Features

#### Knowledge Base Integration

The Security Questionnaire feature integrates with your organization's knowledge base:

* **Published Policies**: Automatically references your published policies
* **Additional Documents**: Upload additional context documents for better answer generation
* **Manual Answers**: Create reusable manual answers for common questions

#### Answer Management

> **Answer Types**
>
> Different ways to answer questions
>
> ### Automated Answers
>
> Answers generated automatically by AI based on your policies and documentation.
>
> ### Manual Answers
>
> Custom answers you create for specific questions. These can be reused across questionnaires.
>
> ### Knowledge Base Answers
>
> Answers linked to specific documents in your knowledge base for traceability.

### Best Practices

1. **Keep Policies Updated**: Ensure your published policies are current and comprehensive
2. **Review All Answers**: Always review AI-generated answers before exporting
3. **Add Context**: Link answers to specific policies or documents when possible
4. **Use Manual Answers**: Create manual answers for frequently asked questions
5. **Organize Knowledge Base**: Maintain a well-organized knowledge base for better answer quality

### Troubleshooting

> **Common Issues**
>
> Solutions to common problems
>
> ### No Published Policies
>
> If you see the onboarding screen, you need to publish at least one policy first.
>
> Navigate to **Policies** → **All Policies** and publish your policies.
>
> ### Questions Not Extracted
>
> If questions aren't extracted properly:
>
> * Ensure the questionnaire file is readable and not corrupted
> * Try re-uploading the file
> * Contact support if issues persist
>
> ### Answers Not Accurate
>
> If generated answers aren't accurate:
>
> * Review and update your published policies
> * Add additional context documents to your knowledge base
> * Manually edit answers as needed

### Support

For additional assistance with Security Questionnaire:

1. Check our [Knowledge Base](https://help.trycomp.ai/security-questionnaire)
2. Contact support at [support@trycomp.ai](mailto:support@trycomp.ai)
3. Join our [Discord community](https://discord.gg/compai) for peer support


# Security Questionnaire Extension
Source: https://www.trycomp.ai/docs/security-questionnaire-extension

Answer security questionnaires directly on the vendor's page — the Chrome extension drafts answers from your Comp AI policies and inserts the ones you approve.

The Comp AI Security Questionnaire extension brings questionnaire answering to wherever the questionnaire actually lives. Instead of exporting a vendor's portal into a spreadsheet, answering it in Comp AI, and copying everything back, the extension finds the questions on the page you're already on, drafts answers from your own policies, and inserts the ones you approve.

It is a companion to [Security Questionnaire](/docs/security-questionnaire) in the app, and draws on the same knowledge: your policies, context entries, knowledge base documents, and questions you've answered before.

## Why it's useful

* **It works where the questionnaire is.** Vendor portals, plain web forms, Google Forms and Google Sheets — no export/import round trip.
* **It drafts from what you've already written.** Answers come from your organization's policies and prior answers, not from generic boilerplate.
* **Nothing is inserted without you.** Every draft is editable and every insertion is an explicit action.
* **It tells you when it doesn't know.** Questions with no supporting material are flagged **Needs review** rather than answered with a guess.

## Install

1. Install **Comp AI Security Questionnaire** from the Chrome Web Store.
2. Pin it to your toolbar so the icon is always visible.
3. Click the Comp AI icon and choose **Sign in**. If you're already signed in to Comp AI in this browser, the extension uses that session.

## Answering a questionnaire

1. Open the questionnaire in your browser.
2. Click the Comp AI icon, then **Open review panel**. Every question the extension detected is listed there.
3. The first time you use the extension on a new site, confirm which Comp AI workspace applies. This keeps answers from one customer's workspace out of another's.
4. Choose **Generate** for a single question, or **Generate all**.
5. Review each draft. Edit anything you want to change, then **Approve** it (or **Approve all**).
6. Choose **Insert approved** to write your approved answers back into the page.

Each answer shows a confidence level and the number of sources behind it. Low-confidence and **Needs review** answers are worth a closer look before you approve them.

> [!NOTE]
>
> Generating again over the whole list will not overwrite answers you have
> edited or approved. To replace one of those, regenerate that specific
> question. To clear the list and begin again, use **Start over**.

### Answering one question on the page

Click into an answer field. If the extension recognizes the question, a small Comp AI button appears in the field's corner. Click it to draft an answer, edit it if you like, then choose **Insert**.

The button only shows in the field you're in, so the page doesn't fill up with buttons.

## Google Sheets

When a questionnaire arrives as a spreadsheet, the extension asks which columns to use — a question column and an answer column, plus the row range. Confirm the mapping once and it is remembered for that sheet.

Approved answers are then written into the answer column, in the rows the questions came from. The first time, Google asks you to allow Comp AI to edit the spreadsheet; once you allow it, **Insert into sheet** fills the cells for you. If you decline, or Google can't be reached, the extension walks you through pasting the answers instead.

> [!NOTE]
>
> While Google finishes reviewing the app, it may show a warning that the app
> isn't verified. Allowing access lets Comp AI read and edit your Google
> Sheets. The extension only uses it on the sheet you have open, when you
> insert: it reads the question column to find the right rows, writes your
> approved answers into the answer column, and turns on text wrapping in those
> cells. To allow it, choose **Advanced**, then **Go to Comp AI**. If you'd
> rather not, go back: you can still paste the answers in yourself.

## Google Forms and Google Docs

**Google Forms** works like any other web form: click into an answer field and a Comp AI button appears in its corner. Approved answers are inserted directly.

**Google Docs** does not support reliable automated insertion, so the extension collects your approved answers and copies them to the clipboard for you to paste in.

## Switching workspaces

The active workspace is shown at the top of the side panel. If you switch it, or sign in as someone else, every answer in the panel is cleared and you will be asked to confirm the site again. Answers you already inserted into the page stay there. This is deliberate — it prevents one organization's answers from being pasted into another organization's questionnaire.

## Permissions

The extension asks for access to the websites you visit. Security questionnaires are hosted on many different vendor domains and there is no fixed list to allow, so it needs to be able to look at the page you open.

In practice:

* It examines pages to locate questionnaire fields. You can turn this off for any site with **Detect questions** in the extension menu.
* The only page content sent to Comp AI is the text of a question you ask it to answer.
* It does not send page contents or browsing history.
* Answers are written into the page only when you choose to insert them.
* For Google Sheets, it asks Google for permission to read and edit spreadsheets. That access stays in your browser and is used only on the sheet you have open, when you insert: to read the question column, write your approved answers into the answer column, and wrap the text in those cells.

## Troubleshooting

**No questions detected.** Check that **Detect questions** is on for this site in the extension menu. Not every layout is recognized: use **Refresh** after the page has fully loaded. Questions rendered inside a nested frame may not be reachable.

**No Comp AI button in a field.** The button appears only while you're in a field the extension recognizes as a question. If it never appears on a site, detection may be off there: turn on **Detect questions** in the extension menu, or choose **Turn on for this site** in the side panel.

**"Extension context invalidated."** The extension was reloaded or updated while the tab was open. Refresh the tab.

**An answer says "Needs review — no knowledge-base match."** Comp AI has nothing to base that answer on. Add the relevant policy or a knowledge base document, or answer that question manually.

**Sign-in problems.** Confirm you are signed in to Comp AI in the same browser profile, then reopen the side panel.


# Docker Self-Hosting
Source: https://www.trycomp.ai/docs/self-hosting/docker

Deploy Comp with Docker Compose using per-service environment files

## Overview

This guide covers running Comp with Docker Compose. The stack includes:

| Service | Purpose | Port |
| - | - | - |
| `migrator` | Runs Prisma migrations against your database | - |
| `seeder` | Loads reference data (frameworks, controls) | - |
| `app` | Main Comp application | 3000 |
| `portal` | Customer trust portal | 3002 |

## Prerequisites

* Docker Desktop or Docker Engine installed
* External PostgreSQL 14+ with SSL (e.g., Neon, DigitalOcean, RDS)
* [Resend](https://resend.com) account for transactional email
* [Trigger.dev](https://cloud.trigger.dev) account for background workflows

## Environment File Layout

> [!WARNING]
>
> Docker uses **per-service env files**, not a root `.env` file.

| File | Services |
| - | - |
| `packages/db/.env` | migrator, seeder |
| `apps/app/.env` | app |
| `apps/portal/.env` | portal |

Each service reads only its designated env file via `env_file:` in `docker-compose.yml`.

## Minimal Required Environment

For a functional Docker deployment, you need:

> **packages/db/.env**
>
> ```bash theme={null}
> DATABASE_URL="postgresql://user:pass@host:5432/db?sslmode=require"
> ```

> **apps/app/.env**
>
> ```bash theme={null}
> # Database
> DATABASE_URL="postgresql://user:pass@host:5432/db?sslmode=require"
>
> # Auth
> AUTH_SECRET="<openssl rand -base64 32>"
> SECRET_KEY="<openssl rand -base64 32>"
> BETTER_AUTH_URL="https://app.yourdomain.com"
> NEXT_PUBLIC_BETTER_AUTH_URL="https://app.yourdomain.com"
> NEXT_PUBLIC_PORTAL_URL="https://portal.yourdomain.com"
>
> # Email
> RESEND_API_KEY="re_..."
>
> # Workflows (required)
> TRIGGER_SECRET_KEY="tr_..."
>
> # Revalidation
> REVALIDATION_SECRET="<random string>"
> ```

> **apps/portal/.env**
>
> ```bash theme={null}
> # Database
> DATABASE_URL="postgresql://user:pass@host:5432/db?sslmode=require"
>
> # Auth
> BETTER_AUTH_SECRET="<openssl rand -base64 32>"
> BETTER_AUTH_URL="https://portal.yourdomain.com"
> NEXT_PUBLIC_BETTER_AUTH_URL="https://portal.yourdomain.com"
>
> # Email
> RESEND_API_KEY="re_..."
> ```

See the [Environment Reference](/docs/self-hosting/env-reference) for all variables.

## Build-Time vs Runtime Variables

| Phase | Variables | How They're Set |
| - | - | - |
| Build-time | `NEXT_PUBLIC_*` | Docker build args in `docker-compose.yml` |
| Runtime | Everything else | Service env files (`.env`) |

The Dockerfile defines these build args for the app:

* `NEXT_PUBLIC_BETTER_AUTH_URL`
* `NEXT_PUBLIC_PORTAL_URL`
* `NEXT_PUBLIC_POSTHOG_KEY`
* `NEXT_PUBLIC_POSTHOG_HOST`
* `NEXT_PUBLIC_IS_DUB_ENABLED`
* `NEXT_PUBLIC_API_URL`

For portal, only `NEXT_PUBLIC_BETTER_AUTH_URL` is used at build time.

> [!NOTE]
>
> `docker-compose.yml` passes build args from shell environment variables (e.g., `${BETTER_AUTH_URL}`). Export these before running `docker compose build`, or set them inline.

## Build & Run

### 1. Prepare Environment Files

```bash theme={null}
# Copy examples to create your env files
cp packages/db/.env.example packages/db/.env
cp apps/app/.env.example apps/app/.env
cp apps/portal/.env.example apps/portal/.env

# Edit each file with your production values
```

### 2. Export Build Args

Export the build-time variables needed by `docker-compose.yml`:

```bash theme={null}
export BETTER_AUTH_URL="https://app.yourdomain.com"
export BETTER_AUTH_URL_PORTAL="https://portal.yourdomain.com"
```

### 3. Build Images

```bash theme={null}
docker compose build --no-cache
```

### 4. Run Migrations & Seed

```bash theme={null}
docker compose run --rm migrator
docker compose run --rm seeder
```

> [!NOTE]
>
> **migrator** runs `prisma migrate deploy` — safe to run repeatedly.\
> **seeder** upserts reference data (frameworks, controls) — idempotent.

### 5. Start Services

```bash theme={null}
docker compose up -d app portal
```

### 6. Verify Health

```bash theme={null}
curl -s http://localhost:3000/api/health
curl -s http://localhost:3002/
```

## Deploy Trigger.dev Tasks

Trigger.dev runs as a hosted service. Deploy your tasks from your workstation:

```bash theme={null}
cd apps/app
bunx trigger.dev@latest login
bunx trigger.dev@latest deploy
```

Set `TRIGGER_SECRET_KEY` in `apps/app/.env` from your Trigger.dev project settings.

## Fresh Install (Optional Clean)

To remove all images and volumes for a clean rebuild:

```bash theme={null}
docker compose down --rmi all --volumes --remove-orphans
docker builder prune --all --force
```

## Logging

Docker Compose is configured with log rotation to prevent disk exhaustion. All services use the `json-file` driver with these defaults:

| Setting | Value | Description |
| - | - | - |
| `max-size` | 10m | Rotate logs at 10 MB |
| `max-file` | 5 | Keep up to 5 rotated files (\~50 MB per service) |
| `compress` | true | Compress rotated files |

### Viewing Logs

```bash theme={null}
# Tail logs for a specific service
docker compose logs -f app

# Tail multiple services
docker compose logs -f app portal

# View last 100 lines
docker compose logs --tail=100 app

# View logs for one-shot jobs
docker compose logs migrator
docker compose logs seeder
```

### Custom Log Configuration

To adjust logging for a specific service (e.g., if `app` is particularly chatty), create a `docker-compose.override.yml`:

```yaml theme={null}
services:
  app:
    logging:
      driver: json-file
      options:
        max-size: '50m'
        max-file: '10'
        compress: 'true'
```

> [!NOTE]
>
> For centralized logging (ELK, Loki, Splunk), you can switch the logging driver to `fluentd`, `gelf`, or `loki`. See Docker's [logging driver documentation](https://docs.docker.com/engine/logging/configure/).

## Production Tips

> **HTTPS & Domains**
>
> Place a reverse proxy (nginx, Caddy, Traefik) in front. Update `BETTER_AUTH_URL` and `NEXT_PUBLIC_BETTER_AUTH_URL` to your public HTTPS domains.

> **Strong Secrets**
>
> Generate secrets with `openssl rand -base64 32`. Rotate periodically.

> **Database Security**
>
> Require SSL. Restrict network access via VPC, IP allowlist, or private networking.

> **Disk Monitoring**
>
> Monitor `/var/lib/docker` disk usage. Periodically prune unused containers and images.

## Troubleshooting

### Builds succeed but containers crash at startup

The Dockerfile sets `SKIP_ENV_VALIDATION=true` at build time, so missing env vars are only caught at runtime.

Check logs to identify missing variables:

```bash theme={null}
docker compose logs app
docker compose logs portal
```

Look for errors mentioning `process.env.*` or "Missing env var", then compare with the [Environment Reference](/docs/self-hosting/env-reference).

### Common Misconfigurations

| Issue | Solution |
| - | - |
| Using root `.env` | Docker reads per-service env files only |
| Missing `DATABASE_URL` | Must be set in all three env files |
| Missing `TRIGGER_SECRET_KEY` | Required in `apps/app/.env` for workflows |
| Mismatched auth URLs | Ensure `BETTER_AUTH_URL` matches `NEXT_PUBLIC_BETTER_AUTH_URL` |
| Build args not exported | Export `BETTER_AUTH_URL` and `BETTER_AUTH_URL_PORTAL` before build |

### Container won't start

```bash theme={null}
# Check if container exists
docker compose ps -a

# View detailed logs
docker compose logs --tail=100 app
```

### Database connection fails

1. Verify `DATABASE_URL` format: `postgresql://user:pass@host:5432/db?sslmode=require`
2. Ensure your IP is allowlisted in the database firewall
3. Test connectivity: `docker compose run --rm app sh -c "nc -zv <db-host> 5432"`


# Environment Reference
Source: https://www.trycomp.ai/docs/self-hosting/env-reference

Complete environment variable reference for Docker self-hosting

## Legend

| Column | Description |
| - | - |
| **Service** | Which service(s) use this variable: `migrator`, `seeder`, `app`, `portal`, `api` |
| **Phase** | `build` = Docker build arg, `runtime` = loaded from env file at startup |
| **Required** | `required-minimal` = needed for basic deployment, `conditional` = needed for specific features, `optional` = safe to omit |

## Minimal Required Variables

These variables are required for a functional Docker deployment:

| Name | Service(s) | Phase | Notes |
| - | - | - | - |
| `DATABASE_URL` | migrator, seeder, app, portal | runtime | PostgreSQL connection string with `?sslmode=require` |
| `AUTH_SECRET` | app | runtime | 32-byte base64 secret for auth. Generate: `openssl rand -base64 32` |
| `SECRET_KEY` | app | runtime | Encryption key for sensitive data. Generate: `openssl rand -base64 32` |
| `BETTER_AUTH_URL` | app, portal | runtime | Base URL for Better Auth (app or portal's public URL) |
| `NEXT_PUBLIC_BETTER_AUTH_URL` | app, portal | build | Public auth URL (same as `BETTER_AUTH_URL`) |
| `BETTER_AUTH_SECRET` | portal | runtime | Portal-specific auth secret. Generate: `openssl rand -base64 32` |
| `RESEND_API_KEY` | app, portal | runtime | [Resend](https://resend.com) API key for email |
| `TRIGGER_SECRET_KEY` | app | runtime | [Trigger.dev](https://cloud.trigger.dev) project secret key |
| `REVALIDATION_SECRET` | app | runtime | Random string for revalidation. Generate: `openssl rand -base64 16` |
| `NEXT_PUBLIC_PORTAL_URL` | app | build | Public URL of the portal (e.g., `https://portal.yourdomain.com`) |

## All Variables by Category

### Database

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `DATABASE_URL` | migrator, seeder, app, portal | runtime | required-minimal | Format: `postgresql://user:pass@host:5432/db?sslmode=require` |

### Authentication

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `AUTH_SECRET` | app | runtime | required-minimal | Main app auth secret |
| `SECRET_KEY` | app | runtime | required-minimal | Encryption key for sensitive data |
| `BETTER_AUTH_URL` | app, portal | runtime | required-minimal | Base URL for auth |
| `BETTER_AUTH_SECRET` | portal | runtime | required-minimal | Portal auth secret |
| `NEXT_PUBLIC_BETTER_AUTH_URL` | app, portal | build | required-minimal | Public auth URL for client code |
| `AUTH_GOOGLE_ID` | app | runtime | conditional | Google OAuth client ID |
| `AUTH_GOOGLE_SECRET` | app | runtime | conditional | Google OAuth client secret |
| `AUTH_GITHUB_ID` | app | runtime | optional | GitHub OAuth client ID |
| `AUTH_GITHUB_SECRET` | app | runtime | optional | GitHub OAuth client secret |
| `AUTH_MICROSOFT_CLIENT_ID` | app | runtime | conditional | Microsoft/Entra OAuth client ID |
| `AUTH_MICROSOFT_CLIENT_SECRET` | app | runtime | conditional | Microsoft/Entra OAuth client secret |
| `AUTH_MICROSOFT_TENANT_ID` | app | runtime | optional | `common` (default), `organizations`, or tenant GUID to restrict login |

Microsoft sign-in only creates a user, or links to an existing one, when the ID token proves the email address. Accounts already linked keep working. In the Entra app registration, add the optional ID-token claims `email`, `xms_edov`, `verified_primary_email` and `verified_secondary_email`, and leave `acceptMappedClaims` off. Without them, first-time Microsoft sign-ins end with `account_not_linked`.

### Email

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `RESEND_API_KEY` | app, portal | runtime | required-minimal | Resend API key for transactional email |
| `RESEND_DOMAIN` | portal | runtime | optional | Custom domain for sending emails |

### Workflows (Trigger.dev)

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `TRIGGER_SECRET_KEY` | app | runtime | required-minimal | Trigger.dev project secret |
| `REVALIDATION_SECRET` | app | runtime | required-minimal | Server-side revalidation secret |

### AWS S3 Storage

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `APP_AWS_ACCESS_KEY_ID` | app, portal | runtime | conditional | AWS access key |
| `APP_AWS_SECRET_ACCESS_KEY` | app, portal | runtime | conditional | AWS secret key |
| `APP_AWS_REGION` | app, portal | runtime | conditional | AWS region (e.g., `us-east-1`) |
| `APP_AWS_BUCKET_NAME` | app, portal | runtime | conditional | General file storage bucket |
| `APP_AWS_ORG_ASSETS_BUCKET` | app | runtime | conditional | Organization logos, compliance certs |
| `APP_AWS_QUESTIONNAIRE_UPLOAD_BUCKET` | app | runtime | conditional | Security questionnaire uploads |
| `APP_AWS_KNOWLEDGE_BASE_BUCKET` | app | runtime | conditional | Knowledge base documents |
| `APP_AWS_ENDPOINT` | app, portal | runtime | optional | URL for alternative S3-compatible providers |

> [!NOTE]
>
> AWS S3 variables are required for file upload features (attachments, logos, questionnaires). Without them, these features will fail.

### AI Providers

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `OPENAI_API_KEY` | app | runtime | conditional | OpenAI API key for AI features |
| `ANTHROPIC_API_KEY` | app | runtime | optional | Anthropic API key (alternative models) |
| `GROQ_API_KEY` | app | runtime | optional | Groq API key for dashboard chat |
| `FIRECRAWL_API_KEY` | app | runtime | conditional | Firecrawl for vendor research |

### Rate Limiting & Caching (Upstash)

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `UPSTASH_REDIS_REST_URL` | app | runtime | optional | Upstash Redis URL for rate limiting |
| `UPSTASH_REDIS_REST_TOKEN` | app | runtime | optional | Upstash Redis token |
| `UPSTASH_VECTOR_REST_URL` | app | runtime | optional | Upstash Vector for embeddings |
| `UPSTASH_VECTOR_REST_TOKEN` | app | runtime | optional | Upstash Vector token |

### Analytics & Tracking

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `NEXT_PUBLIC_POSTHOG_KEY` | app, portal | build | optional | PostHog project key |
| `NEXT_PUBLIC_POSTHOG_HOST` | app, portal | build | optional | PostHog host (e.g., `/ingest`) |

### Vercel (Trust Portal Domains)

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `VERCEL_ACCESS_TOKEN` | app | runtime | conditional | Vercel API token for portal domains |
| `VERCEL_TEAM_ID` | app | runtime | conditional | Vercel team ID |
| `VERCEL_PROJECT_ID` | app | runtime | conditional | Vercel project ID |
| `NEXT_PUBLIC_VERCEL_URL` | app | build | optional | Vercel deployment URL |

### Slack app (internal `/comp` command)

Used by the API (`apps/api`) for the Comp AI team's `/comp` Slack slash command. Self-hosted deployments can leave these unset; the command then refuses every request.

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `SLACK_SIGNING_SECRET` | api | runtime | optional | Slack app signing secret. Used to verify that requests to `/v1/slack/commands` and `/v1/slack/interactions` come from Slack |
| `SLACK_BOT_TOKEN` | api | runtime | optional | Slack app bot token (`xoxb-…`) with `commands`, `users:read`, `users:read.email`, `usergroups:read`, `channels:read`, `groups:read` and `chat:write`. Used to confirm the caller, read channel members, and post finding summaries and reminders to connected channels. Also set it in the Trigger.dev environment of the API |
| `SLACK_CX_USERGROUP_HANDLE` | api | runtime | optional | Handle of the Slack user group whose members may run `/comp register` (default `customer-success`) |
| `SLACK_ALLOWED_TEAM_ID` | api | runtime | optional | ID of the Slack workspace (`T…`) that can use the command. The API refuses requests from other workspaces |

### MDM (Fleet)

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `FLEET_URL` | app | runtime | conditional | Fleet MDM server URL |
| `FLEET_TOKEN` | app | runtime | conditional | Fleet API token |

### Miscellaneous

| Name | Service(s) | Phase | Required | Notes |
| - | - | - | - | - |
| `NEXT_PUBLIC_API_URL` | app | build | optional | Override API base URL |
| `NEXT_OUTPUT_STANDALONE` | app | runtime | optional | Set `true` for AWS/Docker deployments |
| `SLACK_SALES_WEBHOOK` | app | runtime | optional | Slack webhook for sales notifications |
| `DUB_API_KEY` | app | runtime | optional | Dub.co link shortener API key |
| `DUB_REFER_URL` | app | runtime | optional | Dub.co referral URL |

## Example Minimal Configuration

```bash packages/db/.env theme={null}
DATABASE_URL="postgresql://user:pass@host:5432/comp?sslmode=require"
```

```bash apps/app/.env theme={null}
DATABASE_URL="postgresql://user:pass@host:5432/comp?sslmode=require"
AUTH_SECRET="your-32-byte-secret-here"
SECRET_KEY="your-32-byte-encryption-key"
BETTER_AUTH_URL="https://app.yourdomain.com"
NEXT_PUBLIC_BETTER_AUTH_URL="https://app.yourdomain.com"
NEXT_PUBLIC_PORTAL_URL="https://portal.yourdomain.com"
RESEND_API_KEY="re_your_api_key"
TRIGGER_SECRET_KEY="tr_your_secret_key"
REVALIDATION_SECRET="random-revalidation-string"
```

```bash apps/portal/.env theme={null}
DATABASE_URL="postgresql://user:pass@host:5432/comp?sslmode=require"
BETTER_AUTH_SECRET="your-32-byte-portal-secret"
BETTER_AUTH_URL="https://portal.yourdomain.com"
NEXT_PUBLIC_BETTER_AUTH_URL="https://portal.yourdomain.com"
RESEND_API_KEY="re_your_api_key"
```


# Trust Access
Source: https://www.trycomp.ai/docs/trust-access

Manage Trust Center access requests, NDAs, reviewer grants, audit trails, and shared compliance resources in Comp AI.

## Overview

Trust Access enables secure, controlled access to your compliance documentation for external users. This system manages the complete access lifecycle—from initial requests through NDA signing, access grants, and ongoing management—while maintaining full audit trails for compliance purposes.

## 1. Key Concepts

Trust Access consists of four core components:

* **Access Request:** An external user's initial request to access your compliance documentation.
* **NDA Agreement:** A legally binding document that must be digitally signed before access is granted.
* **Access Grant:** A time-limited authorization window (configurable, default 30 days) during which the user has access.
* **Access Link:** A secure, time-limited email link that authenticates the user and grants portal access.

### Time Limits and Expiration

Each component has specific time constraints:

| Item | Duration | Notes |
| :- | :- | :- |
| **NDA Signing Link** | **7 Days** | Expires if not signed within 7 days. Administrators can resend the link. |
| **Access Grant** | **7–365 Days** | Configurable access window. Default duration is 30 days. |
| **Access Link** | **24 Hours** | Email authentication links expire after 24 hours for security. |

***

## 2. Prerequisites

Before using Trust Access, ensure the following is configured:

1. **Published Trust Portal:** The portal must be published and publicly accessible for users to submit access requests.

***

## 3. Workflow: Step-by-Step

### Step 1: Access Request Submission

When external visitors access your public Trust Portal, they see a **Request Access** button. Clicking this button opens a form where they provide:

* Full name and email address
* Company name and job title
* Reason for requesting access

![Trust Portal with Request Access button](https://mintcdn.com/bubbaaiinc/_DS3Mh90qeqK7soD/images/trust-access-portal-request-button.png?fit=max\&auto=format\&n=_DS3Mh90qeqK7soD\&q=85\&s=ceff3db8fd881b9c70d225cec5a612bd)

![Access Request Form](https://mintcdn.com/bubbaaiinc/_DS3Mh90qeqK7soD/images/trust-access-request-form.png?fit=max\&auto=format\&n=_DS3Mh90qeqK7soD\&q=85\&s=09baf02a3219b0bf92f342d7b2a2e010)

New access requests appear in the **Trust Access Management** dashboard with `Pending` status. If the user already has an active access grant, they see: *"You already have active access."* If a pending request exists, duplicate submissions are blocked.

### Step 2: Administrative Review and Decision

Access the **Trust Access Management** dashboard to view all pending access requests. Each request displays the requester's information, purpose, submission timestamp, and current status.

![Access Request Detail View](https://mintcdn.com/bubbaaiinc/_DS3Mh90qeqK7soD/images/trust-access-admin-request-details.png?fit=max\&auto=format\&n=_DS3Mh90qeqK7soD\&q=85\&s=15cae9507eb3965b78bd5ff50336dcf3)

#### Option A: Approve Access Request

1. Click on the request to view complete details
2. Configure the access grant period (7-365 days, default 30 days)
3. Click **Approve & Send NDA** to proceed

![Approve Access Request with Duration Configuration](https://mintcdn.com/bubbaaiinc/_DS3Mh90qeqK7soD/images/trust-access-admin-approve-duration.png?fit=max\&auto=format\&n=_DS3Mh90qeqK7soD\&q=85\&s=e174354ab624b48fc70878ad94636d01)

Request status changes to `Approved`, a pending NDA agreement is generated, and an email is sent to the requester with an NDA signing link (valid for 7 days). The requester receives an email notification: *"NDA Signature Required"* with a secure link to review and sign the NDA.

![NDA Signature Required Email](https://mintcdn.com/bubbaaiinc/_DS3Mh90qeqK7soD/images/trust-access-email-nda-required.png?fit=max\&auto=format\&n=_DS3Mh90qeqK7soD\&q=85\&s=461f73346e55165cddb3b3498ab82218)

#### Option B: Deny Access Request

1. Provide a reason for denial
2. Click **Deny** to reject the request

![Deny Access Request Dialog](https://mintcdn.com/bubbaaiinc/_DS3Mh90qeqK7soD/images/trust-access-admin-deny-dialog.png?fit=max\&auto=format\&n=_DS3Mh90qeqK7soD\&q=85\&s=1f5de638f60fa3b6482510e24e53f406)

Request status changes to `Denied` and the denial reason is logged in the audit trail. No email notification is sent to the requester.

### Step 3: NDA Signing Process

1. The requester receives an email with subject *"NDA Signature Required"* containing a secure signing link
2. Clicking the link opens a secure page displaying the complete NDA document
3. They provide their digital signature to accept the agreement
4. After signing, they receive confirmation that the NDA has been completed

![NDA Signing Page](https://mintcdn.com/bubbaaiinc/_DS3Mh90qeqK7soD/images/trust-access-nda-signing-page.png?fit=max\&auto=format\&n=_DS3Mh90qeqK7soD\&q=85\&s=017da9ce601b60145f2ecbb9ee574a3f)

NDA status updates to `Signed` in the dashboard, the signed NDA PDF is available for download, and the access grant is automatically activated. The audit log captures the signing timestamp, signer's IP address, User Agent information, and the final signed PDF document.

![Dashboard showing Signed NDA status](https://mintcdn.com/bubbaaiinc/_DS3Mh90qeqK7soD/images/trust-access-admin-nda-signed.png?fit=max\&auto=format\&n=_DS3Mh90qeqK7soD\&q=85\&s=8bc4c45cec972f2b47b6a26ac1e53de6)

If the 7-day signing window expires, administrators see `NDA Link Expired` status and can use **Resend NDA** to generate a new link. If users attempt to access an already-signed NDA link, they are redirected to the portal.

### Step 4: Portal Access Granted

After successfully signing the NDA, users receive an email notification: *"Access Granted"*. This email contains their first **Access Link** (valid for 24 hours).

Once authenticated via the access link, users are presented with a tabbed interface providing access to different features:

![Trust Portal with Access Granted - Navigation tabs](https://mintcdn.com/bubbaaiinc/1A9KM7Y-BLiOxWJQ/images/trust-nav-tabs.png?fit=max\&auto=format\&n=1A9KM7Y-BLiOxWJQ\&q=85\&s=71cf29bfdf4dd37d313ade0527b157ab)

#### Documents Tab (Default)

The **Documents** tab is selected by default and provides access to compliance documentation:

* **Compliance Resources Section:** Browse and read all published, non-archived compliance policies organized by category

![Trust Portal with Access Granted - Compliance Resources Section](https://mintcdn.com/bubbaaiinc/1A9KM7Y-BLiOxWJQ/images/compliance-resources-section.png?fit=max\&auto=format\&n=1A9KM7Y-BLiOxWJQ\&q=85\&s=340fb63d92bb7fe58cdfd09eb854860f)

* **PDF Bundle Generation:** Generate a single PDF bundle containing all accessible policies
  * The downloaded PDF bundle is watermarked with the user's full name, email address, and a unique document identifier

![Trust Portal with Access Granted - Document View](https://mintcdn.com/bubbaaiinc/_DS3Mh90qeqK7soD/images/trust-access-portal-view.png?fit=max\&auto=format\&n=_DS3Mh90qeqK7soD\&q=85\&s=b4d45651fe56181e07084cd82e6e6621)

#### Security Questionnaire Tab

![Trust Portal with Access Granted - Security Questionnaire](https://mintcdn.com/bubbaaiinc/1A9KM7Y-BLiOxWJQ/images/security-questionnaire-section.png?fit=max\&auto=format\&n=1A9KM7Y-BLiOxWJQ\&q=85\&s=5470f88bcc3da5645446a528346bab1c)

The **Security Questionnaire** tab enables external users to automatically parse and answer security questionnaires using the organization's compliance documentation.

**Questionnaire Upload Interface:**

1. **File Upload Field:** Upload your security questionnaire file
   * Supported formats: PDF, CSV, Excel (.xlsx, .xls)
   * File must be readable and not corrupted
   * Maximum file size: 10MB

2. **Output Format Selection:** Choose the format for the processed questionnaire
   * **Excel (.xlsx)** - Default format, editable in Excel
   * **PDF** - Final submission format
   * **CSV** - Simple data exchange format

3. **Upload & Process Button:** Submit the questionnaire for processing
   * The system automatically extracts questions from your file
   * Answers are generated based on the organization's published policies
   * Processing typically takes 5-30 seconds depending on file type and size

After processing, the completed questionnaire is automatically downloaded with all questions answered based on the organization's compliance documentation. Users can review and edit answers before final submission.

> [!NOTE]
>
> Trust Access is API-backed across request intake, grant management, public Trust Center data, and
> reviewer workflows. Public organization automation should use API-key protected endpoints;
> reviewer session calls used by the Trust Portal app are intentionally omitted from the API
> reference.

Access grant status shows as `Active` in the dashboard, the grant expiration date is visible, and all activity (document downloads and questionnaire submissions) is logged for audit purposes.

***

## 4. Managing Active Access

### Reclaiming Access (Expired Access Links)

Access links expire after 24 hours. If a user attempts to use an expired link, they can reclaim access without administrator intervention:

1. Navigate to the Trust Portal
2. Click **Reclaim Access**
3. Enter their email address

![Reclaim Access button and form](https://mintcdn.com/bubbaaiinc/_DS3Mh90qeqK7soD/images/trust-access-reclaim-access.png?fit=max\&auto=format\&n=_DS3Mh90qeqK7soD\&q=85\&s=e9b5e2e8d52316fefe1d03a24602701d)

The response is the same for every email address: *"If this email has active access, a link has been sent to it."* If their access grant is still active, the system emails a new access link. If no email arrives within a few minutes, check spam and try again. If it still does not arrive, contact the organization's trust portal contact, or submit a new access request if the grant may have expired.

### Revoking Access

Access can be revoked at any time through the **Grants** section of the dashboard:

1. Navigate to the **Grants** list in the dashboard
2. Locate the active grant for the user
3. Click **Revoke**
4. Enter a reason for revocation

Grant status immediately changes to `Revoked`, the signed NDA is marked as `Void`, all active access links are immediately invalidated, and the revocation action is logged in the audit trail. Any active access links stop working immediately, and users must submit a new access request if access is needed again.