HashiConf 2024 Now streaming live from Boston! Attend for free
Terraform
Terraform Home

You are viewing documentation for version v202302-1. View latest version.

Policy Checks API

Note: Sentinel and OPA policies are available in the Terraform Cloud Team & Governance tier. OPA policies are not available in Terraform Enterprise.

List Policy Checks

This endpoint lists the policy checks in a run.

Note: The sentinel hash in the result attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk.

GET /runs/:run_id/policy-checks

ParameterDescription
run_idThe ID of the run to list policy checks for.

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results.

ParameterDescription
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 policy checks per page.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/runs/run-CZcmD7eagjhyXavN/policy-checks

Sample Response

{
  "data": [
    {
      "id": "polchk-9VYRc9bpfJEsnwum",
      "type": "policy-checks",
      "attributes": {
        "result": {
          "result": false,
          "passed": 0,
          "total-failed": 1,
          "hard-failed": 0,
          "soft-failed": 1,
          "advisory-failed": 0,
          "duration-ms": 0,
          "sentinel": {...}
        },
        "scope": "organization",
        "status": "soft_failed",
        "status-timestamps": {
          "queued-at": "2017-11-29T20:02:17+00:00",
          "soft-failed-at": "2017-11-29T20:02:20+00:00"
        },
        "actions": {
          "is-overridable": true
        },
        "permissions": {
          "can-override": false
        }
      },
      "relationships": {
        "run": {
          "data": {
            "id": "run-veDoQbv6xh6TbnJD",
            "type": "runs"
          }
        }
      },
      "links": {
        "output": "/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum/output"
      }
    }
  ]
}

Show Policy Check

This endpoint gets information about a specific policy check ID. Policy check IDs can appear in audit logs.

Note: The sentinel hash in the result attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk.

GET /policy-checks/:id

ParameterDescription
idThe ID of the policy check to show.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum

Sample Response

{
  "data": {
    "id": "polchk-9VYRc9bpfJEsnwum",
    "type": "policy-checks",
    "attributes": {
      "result": {
        "result": false,
        "passed": 0,
        "total-failed": 1,
        "hard-failed": 0,
        "soft-failed": 1,
        "advisory-failed": 0,
        "duration-ms": 0,
        "sentinel": {...}
      },
      "scope": "organization",
      "status": "soft_failed",
      "status-timestamps": {
        "queued-at": "2017-11-29T20:02:17+00:00",
        "soft-failed-at": "2017-11-29T20:02:20+00:00"
      },
      "actions": {
        "is-overridable": true
      },
      "permissions": {
        "can-override": false
      }
    },
    "relationships": {
      "run": {
        "data": {
          "id": "run-veDoQbv6xh6TbnJD",
          "type": "runs"
        }
      }
    },
    "links": {
      "output": "/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum/output"
    }
  }
}

Override Policy

This endpoint overrides a soft-mandatory or warning policy.

Note: The sentinel hash in the result attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk.

POST /policy-checks/:id/actions/override

ParameterDescription
idThe ID of the policy check to override.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/policy-checks/polchk-EasPB4Srx5NAiWAU/actions/override

Sample Response

{
  "data": {
    "id": "polchk-EasPB4Srx5NAiWAU",
    "type": "policy-checks",
    "attributes": {
      "result": {
        "result": false,
        "passed": 0,
        "total-failed": 1,
        "hard-failed": 0,
        "soft-failed": 1,
        "advisory-failed": 0,
        "duration-ms": 0,
        "sentinel": {...}
      },
      "scope": "organization",
      "status": "overridden",
      "status-timestamps": {
        "queued-at": "2017-11-29T20:13:37+00:00",
        "soft-failed-at": "2017-11-29T20:13:40+00:00",
        "overridden-at": "2017-11-29T20:14:11+00:00"
      },
      "actions": {
        "is-overridable": true
      },
      "permissions": {
        "can-override": false
      }
    },
    "links": {
      "output": "/api/v2/policy-checks/polchk-EasPB4Srx5NAiWAU/output"
    }
  }
}

Available Related Resources

The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:

Resource NameDescription
runThe run this policy check belongs to.
run.workspaceThe associated workspace of the run.