OOTB policies API reference

Out-of-the-box (OOTB) policies are pre-built policy definitions sourced from curated compliance framework libraries. This API endpoint lets you browse the OOTB policy catalog so you can discover available policies and add them to your policy sets.

Note: HCP Terraform Free edition includes one policy set of up to five policies. In HCP Terraform Standard and Premium editions, you can connect a policy set to a version control repository or create policy set versions with the API. Refer to HCP Terraform pricing for details.

List OOTB policies

GET /ootb-policies

Returns all active OOTB policies from ingested releases of active libraries.

Status	Response	Reason
200	JSON API document (`type: "ootb-policies"`)	Request was successful
400	JSON API error object	Invalid query parameters

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.

Parameter	Description
`organization_name`	Required. The name of the organization.
`filter[kind]`	Optional. Filter policies by policy engine type. Valid values are `sentinel` and `tfpolicy`.
`filter[governed-resources]`	Optional. Filter policies to those governing the given Terraform resource type. Accepts a single value or a comma-separated list (e.g. `aws_s3_bucket,aws_ec2_instance`). Returns policies that govern any of the specified resource types. Valid values are returned by the `getOotbPolicyFilterOptions` endpoint under `data.attributes.governed-resources[]`.
`filter[provider]`	Optional. Filter policies by cloud provider. Accepts a single value or a comma-separated list (e.g. `aws,azure`). Case-insensitive — `AWS` and `aws` both match. Available values are returned by the `getOotbPolicyFilterOptions` endpoint under `data.attributes.providers`.
`filter[service]`	Optional. Filter policies by cloud service. Accepts a single value or a comma-separated list (e.g. `s3,ec2`). Valid values are returned by the `getOotbPolicyFilterOptions` endpoint under `data.attributes.services[]`.
`filter[library]`	Optional. Filter policies by compliance framework library. Accepts a single slug or a comma-separated list of slugs (e.g. `nist-800-53-aws,cis-aws`). Valid slugs are returned by the `getOotbPolicyFilterOptions` endpoint under `data.attributes.libraries[].slug`.
`filter[exclude_policy_set]`	Optional. Exclude OOTB policies already materialized into the given policy set. The value is the policy set's external ID (e.g. `polset-xxxxxxxxxxxxxxxx`). Returns `400` if the policy set does not exist or does not belong to `organization_name`.
`search[name]`	Optional. Search policies by name (case-insensitive partial match).
`sort`	Optional. Sort policies by name. Valid values are `name` (ascending) and `-name` (descending).
`page[number]`	Optional. The page number to retrieve. If omitted, the endpoint returns the first page.
`page[size]`	Optional. The number of items to retrieve per page. Defaults to `20`.
`include`	Optional. Comma-separated list of relationships to sideload. The only accepted value is `ootb-policy-libraries` (hyphens or underscores accepted). When included, each policy resource gains a `relationships.ootb-policy-libraries` object and the top-level `included` array contains library references with only a `name` attribute (`type: "ootb-policy-libraries"`, `id` = slug).

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  "https://app.terraform.io/api/v2/ootb-policies?organization_name=my-organization"

Sample Request with filters

curl \
  --header "Authorization: Bearer $TOKEN" \
  "https://app.terraform.io/api/v2/ootb-policies?organization_name=my-organization&filter%5Bkind%5D=sentinel&filter%5Bprovider%5D=aws"

Sample Response

{
  "data": [
    {
      "id": "ootbpol-xxxxxxxxxxxxxxxx",
      "type": "ootb-policies",
      "attributes": {
        "name": "s3-bucket-versioning-enabled",
        "description": "Ensures that S3 bucket versioning is enabled.",
        "kind": "sentinel",
        "provider": "aws",
        "service": "s3",
        "governed-resources": [
          "aws_s3_bucket"
        ],
        "slug": "s3-bucket-versioning-enabled",
        "control-source": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html"
      },
      "relationships": {},
      "links": {
        "download": "https://app.terraform.io/api/v2/ootb-policies/ootbpol-xxxxxxxxxxxxxxxx/download"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/ootb-policies?organization_name=my-organization&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/ootb-policies?organization_name=my-organization&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/ootb-policies?organization_name=my-organization&page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Sample Response with `include=ootb-policy-libraries`

curl \
  --header "Authorization: Bearer $TOKEN" \
  "https://app.terraform.io/api/v2/ootb-policies?organization_name=my-organization&include=ootb-policy-libraries"

{
  "data": [
    {
      "id": "ootbpol-xxxxxxxxxxxxxxxx",
      "type": "ootb-policies",
      "attributes": {
        "name": "s3-bucket-versioning-enabled",
        "description": "Ensures that S3 bucket versioning is enabled.",
        "kind": "sentinel",
        "provider": "aws",
        "service": "s3",
        "governed-resources": [
          "aws_s3_bucket"
        ],
        "slug": "s3-bucket-versioning-enabled",
        "control-source": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html"
      },
      "relationships": {
        "ootb-policy-libraries": {
          "data": [
            { "type": "ootb-policy-libraries", "id": "nist-800-53-aws" }
          ]
        }
      },
      "links": {
        "download": "https://app.terraform.io/api/v2/ootb-policies/ootbpol-xxxxxxxxxxxxxxxx/download"
      }
    }
  ],
  "included": [
    {
      "id": "nist-800-53-aws",
      "type": "ootb-policy-libraries",
      "attributes": {
        "name": "NIST 800-53 for AWS"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/ootb-policies?organization_name=my-organization&include=ootb-policy-libraries&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/ootb-policies?organization_name=my-organization&include=ootb-policy-libraries&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/ootb-policies?organization_name=my-organization&include=ootb-policy-libraries&page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

The GET endpoint above can optionally return related resources if you include the include query parameter.

Resource	Description
`ootb-policy-libraries`	The compliance framework libraries this policy belongs to. Each included item has `type: "ootb-policy-libraries"`, `id` equal to the library slug, and an `attributes.name` field with the human-readable library name.

Attributes

The following attributes are returned for each ootb-policies resource:

Attribute	Type	Description
`name`	string	The name of the policy.
`description`	string or null	Policy description.
`kind`	string	The policy engine type. One of `sentinel` or `tfpolicy`.
`provider`	string	Cloud provider the policy targets, stored lower-cased (e.g. `aws`, `azure`, `gcp`). Use as the value of `filter[provider]` on the list endpoint.
`service`	string	Cloud service the policy targets (e.g. `s3`, `iam`, `compute`). Use as the value of `filter[service]` on the list endpoint.
`governed-resources`	array[string]	Array of Terraform resource types this policy governs.
`slug`	string	URL-friendly unique identifier for the policy.
`control-source`	string or null	Source location (docs/repository URL) for this policy. Null when no active library release is available.

Links

Each ootb-policies resource includes a links object:

Key	Type	Description
`download`	string or null	URL to download the latest version of this policy's source content.