Drata Integration
Connect Drata to let agents read your compliance posture:
- Which monitoring Tests are failing, and the exact resources causing each failure
- The Controls those tests map to
- Per-framework readiness (for example, a SOC 2 readiness percentage)
- Your risk register
Instead of manually opening Drata each week and clicking into every failing test, an agent can pull the failing set. It can see the affected resource and the precise assertion that failed. It can use that as the input to draft a remediation change.
Read-only. Autoheal reads your Drata Tests, Controls, Frameworks, and Risks. It never creates or modifies anything in Drata. Any change to your systems to fix a deficiency happens in your own repositories as a pull request that a human reviews. Autoheal never writes that change to Drata.
Capabilities
Once connected, agents can:
| Capability | Description |
|---|---|
| List failing tests | Read Drata monitoring tests filtered to checkResultStatus = FAILED — the deficiencies behind a framework score below 100% |
| Affected resources | For a failing test, list the exact resources causing it (resourceName, resourceArn, accountName, region) with a structured cause describing the failed assertion |
| Controls | Read the controls a test maps to (code, name, description) |
| Framework readiness | Read each framework's readiness (numReadyInScopeRequirements / numInScopeRequirements) — the percentage you track each week |
| Risks | Read the risk register for severity context (score, impact, likelihood, treatmentPlan, status) |
| Workspaces | Enumerate workspaces for multi-product accounts |
Agents read Drata through its Public API v2 (https://public-api.drata.com/public/v2). Data is workspace-scoped. Most accounts have a single workspace (id 1).
Prerequisites
- A Drata account on the Advanced plan or above (Drata limits programmatic API access to Advanced+. Foundation has no API access.)
- An OAuth Application (recommended) or an API key created in Drata with read-only / auditor scopes
Authentication
Autoheal supports two authentication modes. Pick one when you add the integration. Both are read-only.
| Mode | What you provide | When to use |
|---|---|---|
| OAuth 2.0 (Client Credentials) — recommended | OAuth Client ID + Secret, plus the Token URL and Audience from your Drata OAuth Application | Best security posture — short-lived scoped tokens, no long-lived key stored. The right choice for production. |
| API Key | A Drata API key | Simplest to configure. Created under Settings → API Keys. The full key is shown only once. Good for a quick start. |
Both also take a Region — us (default), eu, or apac — which selects the correct API base URL.
Setup
- Create the credential in Drata
OAuth 2.0 (recommended): In Drata, create an OAuth Application (OAuth setup guide). Give it read scopes covering monitoring tests, controls, risks, and workspaces (
read:monitor-test,read:controls,read:control,read:risk,read:risk-registers,read:workspace). From the application's Token Request Details panel, copy the Client ID, Client Secret, Token URL, and Audience. Drata auto-fills the Token URL and Audience for your tenant and region.API Key: In Drata, go to Settings → API Keys → Create API Key. Choose Read only scopes. Leave Allowed IP Addresses blank, unless your policy requires pinning an egress IP. Copy the key immediately. The key is shown only once.
- Add the Integration in Autoheal
- Go to Integrations in Autoheal and click Drata.
- Enter a name (e.g. "Production Drata").
- Configure Credentials
Select your Region (US / EU / APAC). Then choose an Authentication mode and complete its fields:
- OAuth 2.0 (Client Credentials): Client ID + Client Secret + Token URL + Audience
- API Key: paste the key
- Test and Save
Click Test Connection to check the connection, then click Save. The connection test lists your workspaces.
Required Permissions
Autoheal only reads. Grant a read-only / auditor role or the equivalent read scopes:
| Drata resource | Access | Why it's needed |
|---|---|---|
| Monitoring Tests | read | Failing tests + their failing resources (the findings) |
| Controls | read | Control mapping and detail |
| Frameworks | read | Per-framework readiness percentages |
| Risks | read | Severity context |
| Workspaces | read | Enumerate workspaces to scope other reads |
Example Queries
Once connected, you can ask an agent questions like:
Which monitoring tests are failing right now, and what resources are causing each?
What's our SOC 2 readiness, and which failing tests are dragging it down?
For the failing "AWS S3 Object-Level Logging" test, show me the affected resources and why each one failed.
List the current risks by severity.
Troubleshooting
401 Unauthorized
- Check that the API key is correct, active, and not expired. A key is shown only once, at creation. A partial copy is the most common cause.
- Check that the selected Region matches your Drata tenant. A US key on the EU host, or vice versa, returns 401.
- If you set Allowed IP Addresses on the key, check that it matches the egress IP Autoheal calls from. Otherwise, clear it.
- Check that your Drata plan is Advanced or above. Foundation has no API access.
403 Forbidden
- The key's role/scopes lack read access to that resource. Grant read on Monitoring Tests, Controls, Risks, Frameworks, and Workspaces.
OAuth: token request failed
- Check that the Token URL and Audience were copied exactly from the OAuth Application's Token Request Details panel. Both values are specific to your tenant and region.
- The Token URL must be
https - Check that the OAuth Application is enabled and granted the read scopes above. Effective access is the intersection of the granted scopes and the application's role.
Empty results / a test isn't shown
- Data is workspace-scoped. For multi-product accounts, check that you use the correct workspace id. Use the workspaces list. Single-product accounts use id
1. FAILEDonly returns currently-failing tests. A test that just recovered won't appear.
Rate limited (429)
- Drata enforces 500 requests/minute per source IP. Agents paginate and retry. Very large accounts simply take longer.