Policy Groups

The PolicyGroup resource

A policy group represents the collection of OPA policies stored in a VCS repository.

When linked to an environment, the policy group will participate in the policy check phase of every run in that environment.

Key path

Description

type* (string)

Available values: policy-groups

id (string)

attributes.error-message (string)

This field contains the error description when the group’s status is errored.

attributes.name* (string)

The policy group name must be unique within the account and contain only letters, numbers, dashes

attributes.opa-version (string)

The version of Open Policy Agent to use for the policy evaluation.

If omitted, the system default version is assigned.

attributes.status (string)

Policy group current status.

  • fetching - waiting for policies to be synchronized with VCS.

  • active - synchronization completed, policy group is ready.

  • errored - synchronization has failed. Attribute error-message contains the details.

attributes.vcs-repo.branch (string)

Branch of a repository the policy group is associated with. If omitted, the repository default branch will be used.

attributes.vcs-repo.identifier* (string)

A reference to your VCS repository.

For GitHub, GitHub Enterprise and GitLab the format is <org>/<repo>. For Azure DevOps Services the format is <org>/<project>/<repo>.

attributes.vcs-repo.path (string)

The sub-directory of the VCS repository where OPA policies are stored. The scalr-policy.hcl file must exist in this directory. Files and directories outside this directory will be ignored during a sync from VCS, and changing them won’t trigger a policy group update.

If omitted or submitted as an empty string, this defaults to the repository’s root.

relationships.account* (object)

The account this policy group belongs to.

relationships.account.data.type* (string)

Available values: accounts

relationships.account.data.id* (string)

relationships.environments (object)

List of environments this policy group is linked to.

relationships.environments.data* (array)

relationships.policies (object)

List of OPA policies this group contains.

relationships.policies.data* (array)

relationships.vcs-provider* (object)

The policy group’s VCS provider.

relationships.vcs-provider.data.type* (string)

Available values: vcs-providers

relationships.vcs-provider.data.id* (string)

relationships.vcs-revision (object)

The Git commit information when the policy group was fetched from VCS.

relationships.vcs-revision.data.type* (string)

Available values: vcs-revisions

relationships.vcs-revision.data.id* (string)

relationships.workspaces (object)

List of workspaces affected by this policy group.

relationships.workspaces.data* (array)

links.self (string)

The Policy resource

A policy provides details of a single OPA policy as declared in scalr-policy.hcl.

Key path

Description

type* (string)

Available values: policies

id (string)

attributes.enabled (boolean)

If set to false, the policy will not be evaluated during a run.

attributes.enforced-level (string)

Available values: hard-mandatory, soft-mandatory, advisory

The policy’s enforcement level.

  • hard-mandatory - cannot be overridden.

  • soft-mandatory - can be overridden through an approval by account admins and other authorized roles.

  • advisory - provides a warning only.

attributes.name (string)

The name of the policy.

relationships.policy-group (object)

The policy group this policy belongs to.

relationships.policy-group.data.type* (string)

Available values: policy-groups

relationships.policy-group.data.id* (string)

links.self (string)

Get a Policy

GET /api/iacp/v3/policies/{policy}

Show details of a specific OPA policy.

Parameters

  • policy (string) – The ID of the policy to show.

Example Request:

GET /api/iacp/v3/policies/{policy} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes

  • 200 OK – Success.

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – User not authorized or policy not found.

  • 4XX – Client error.

  • 5XX – Server error.

List Policy Groups

GET /api/iacp/v3/policy-groups

This endpoint returns a list of policy groups.

Query Parameters

  • filter[master-policy-group] (string) – Filter dry groups by master policy group id

  • filter[policy-group] (string) – Filter by policy group id

  • filter[environment] (string) – Environment filter

  • filter[account] (string) – Account filter

  • filter[software-version] (string) – The ID of the software version

  • filter[name] (string) – The policy group name filter.

  • include (array) – The comma-separated list of relationship paths. (Available values: account, environments, policies, vcs-provider, vcs-revision, workspaces)

  • query (string) – Query string

  • sort (array) – The comma-separated list of attributes. (Available values: account, name, status)

  • page[number] (string) – Page number

  • page[size] (string) – Page size

Example Request:

GET /api/iacp/v3/policy-groups HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes

  • 200 OK –

    Success.

    Example Respone:

    HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Preference-Applied: profile=preview

{
  "data": [
    {
      "attributes": {
        "error-message": null,
        "name": "Tags",
        "opa-version": "0.29.4",
        "status": "active",
        "vcs-repo": {
          "branch": "master",
          "identifier": "my_org/repo",
          "path": "policies/tags"
        }
      },
      "id": "pgrp-svsu1tn68mhevuo",
      "links": {
        "self": "https://my.scalr.io/api/iacp/v3/policy-groups/pgrp-svsu1tn68mhevuo"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "acc-svrcncgh453bi8g",
            "type": "accounts"
          }
        },
        "environments": {
          "data": [
            {
              "id": "env-svrcnchebt61e30",
              "type": "environments"
            },
            {
              "id": "env-svrdqa8d7mhaimo",
              "type": "environments"
            }
          ]
        },
        "policies": {
          "data": [
            {
              "id": "policy-ta3cb9im2kdck4g",
              "type": "policies"
            },
            {
              "id": "policy-tmttegdtd1rg0fg",
              "type": "policies"
            }
          ]
        },
        "vcs-provider": {
          "data": {
            "id": "vcs-svsmeap82s0tsho",
            "type": "vcs-providers"
          }
        },
        "vcs-revision": {
          "data": {
            "id": "vrb-svsu1tn54f6brfg",
            "type": "vcs-revisions"
          }
        },
        "workspaces": {
          "data": [
            {
              "id": "ws-tmtt98uuhs7n7do",
              "type": "workspaces"
            },
            {
              "id": "ws-tmtt9e4fn037nq8",
              "type": "workspaces"
            },
            {
              "id": "ws-tmtt9ir5ra2ta6o",
              "type": "workspaces"
            }
          ]
        }
      },
      "type": "policy-groups"
    },
    {
      "attributes": {
        "error-message": "scalr-policy.hcl not found in repository",
        "name": "Instance types",
        "opa-version": "0.29.4",
        "status": "errored",
        "vcs-repo": {
          "branch": "master",
          "identifier": "Scalr/tf-revizor-fixtures",
          "path": "policies/instances"
        }
      },
      "id": "pgrp-svsu2pkubpob58o",
      "links": {
        "self": "https://my.scalr.io/api/iacp/v3/policy-groups/pgrp-svsu2pkubpob58o"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "acc-svrcncgh453bi8g",
            "type": "accounts"
          }
        },
        "environments": null,
        "policies": null,
        "vcs-provider": {
          "data": {
            "id": "vcs-svsmeap82s0tsho",
            "type": "vcs-providers"
          }
        },
        "vcs-revision": {
          "data": {
            "id": "vrb-svsu2pkt28f32go",
            "type": "vcs-revisions"
          }
        },
        "workspaces": null
      },
      "type": "policy-groups"
    }
  ],
  "included": null,
  "links": {
    "first": "https://my.scalr.io/api/iacp/v3/policy-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "last": "https://my.scalr.io/api/iacp/v3/policy-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "next": null,
    "prev": null,
    "self": "https://my.scalr.io/api/iacp/v3/policy-groups?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "next-page": null,
      "prev-page": null,
      "total-count": 2,
      "total-pages": 1
    }
  }
}

  • 403 Forbidden – User unauthorized to perform this action.

  • 4XX – Client error.

  • 5XX – Server error.

Create a Policy Group

POST /api/iacp/v3/policy-groups

Create a new policy group in the account.

Query Parameters

  • include (array) – The comma-separated list of relationship paths. (Available values: account, environments, policies, vcs-provider, vcs-revision, workspaces)

Request body:

Key path

Description

data.type* (string)

Available values: policy-groups

data.id (string)

data.attributes.name* (string)

The policy group name must be unique within the account and contain only letters, numbers, dashes

data.attributes.opa-version (string)

The version of Open Policy Agent to use for the policy evaluation.

If omitted, the system default version is assigned.

data.attributes.vcs-repo.branch (string)

Branch of a repository the policy group is associated with. If omitted, the repository default branch will be used.

data.attributes.vcs-repo.identifier* (string)

A reference to your VCS repository.

For GitHub, GitHub Enterprise and GitLab the format is <org>/<repo>. For Azure DevOps Services the format is <org>/<project>/<repo>.

data.attributes.vcs-repo.path (string)

The sub-directory of the VCS repository where OPA policies are stored. The scalr-policy.hcl file must exist in this directory. Files and directories outside this directory will be ignored during a sync from VCS, and changing them won’t trigger a policy group update.

If omitted or submitted as an empty string, this defaults to the repository’s root.

data.relationships.account* (object)

The account this policy group belongs to.

data.relationships.account.data.type* (string)

Available values: accounts

data.relationships.account.data.id* (string)

data.relationships.vcs-provider* (object)

The policy group’s VCS provider.

data.relationships.vcs-provider.data.type* (string)

Available values: vcs-providers

data.relationships.vcs-provider.data.id* (string)

Example Request:

POST /api/iacp/v3/policy-groups HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data": {
    "attributes": {
      "name": "Limit cost",
      "opa-version": "0.30.2",
      "vcs-repo": {
        "branch": "master",
        "identifier": "my_org/repo",
        "path": "policies/cost"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-svrcncgh453bi8g",
          "type": "accounts"
        }
      },
      "vcs-provider": {
        "data": {
          "id": "vcs-svsmeap82s0tsho",
          "type": "vcs-providers"
        }
      }
    },
    "type": "policy-groups"
  }
}
Status Codes

  • 201 Created –

    Successfully created.

    Example Respone:

    HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
Preference-Applied: profile=preview

{
  "data": {
    "attributes": {
      "error-message": null,
      "name": "Limit cost",
      "opa-version": "0.30.2",
      "status": "fetching",
      "vcs-repo": {
        "branch": "master",
        "identifier": "my_org/repo",
        "path": "policies/cost"
      }
    },
    "id": "pgrp-tmttm6aiq13a6bo",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/policy-groups/pgrp-tmttm6aiq13a6bo"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-svrcncgh453bi8g",
          "type": "accounts"
        }
      },
      "environments": null,
      "policies": null,
      "vcs-provider": {
        "data": {
          "id": "vcs-svsmeap82s0tsho",
          "type": "vcs-providers"
        }
      },
      "vcs-revision": {
        "data": {
          "id": "vrb-tmttm7g1b4nlvqo",
          "type": "vcs-revisions"
        }
      },
      "workspaces": null
    },
    "type": "policy-groups"
  },
  "included": null,
  "meta": null
}

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Relationship not found or user unauthorized to perform action.

  • 409 Conflict – Quota exceeded error.

  • 422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).

  • 4XX – Client error.

  • 5XX – Server error.

Delete a Policy Group

DELETE /api/iacp/v3/policy-groups/{policy_group}

This endpoint deletes a policy group by ID. Only an unused policy group (that is not linked to any environment) can be removed.

Parameters

  • policy_group (string) – The ID of the policy group to delete.

Status Codes

  • 204 No Content – Deleted.

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Policy group not found or user unauthorized to perform action.

  • 409 Conflict – Can’t be deleted. The policy group is in use.

  • 4XX – Client error.

  • 5XX – Server error.

Get a Policy Group

GET /api/iacp/v3/policy-groups/{policy_group}

Show details of a specific policy group.

Parameters

  • policy_group (string) – The ID of the policy group to show.

Query Parameters

  • include (array) – The comma-separated list of relationship paths. (Available values: account, environments, policies, vcs-provider, vcs-revision, workspaces)

Example Request:

GET /api/iacp/v3/policy-groups/{policy_group} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes

  • 200 OK – Success.

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – User not authorized or policy group not found.

  • 4XX – Client error.

  • 5XX – Server error.

Update a Policy Group

PATCH /api/iacp/v3/policy-groups/{policy_group}

This endpoint updates a policy group by ID.

Parameters

  • policy_group (string) – The ID of the policy group to update.

Query Parameters

  • include (array) – The comma-separated list of relationship paths. (Available values: account, environments, policies, vcs-provider, vcs-revision, workspaces)

Request body:

Key path

Description

data.type* (string)

Available values: policy-groups

data.id (string)

data.attributes.name* (string)

The policy group name must be unique within the account and contain only letters, numbers, dashes

data.attributes.opa-version (string)

The version of Open Policy Agent to use for the policy evaluation.

If omitted, the system default version is assigned.

data.attributes.vcs-repo.branch (string)

Branch of a repository the policy group is associated with. If omitted, the repository default branch will be used.

data.attributes.vcs-repo.identifier* (string)

A reference to your VCS repository.

For GitHub, GitHub Enterprise and GitLab the format is <org>/<repo>. For Azure DevOps Services the format is <org>/<project>/<repo>.

data.attributes.vcs-repo.path (string)

The sub-directory of the VCS repository where OPA policies are stored. The scalr-policy.hcl file must exist in this directory. Files and directories outside this directory will be ignored during a sync from VCS, and changing them won’t trigger a policy group update.

If omitted or submitted as an empty string, this defaults to the repository’s root.

data.relationships.account* (object)

The account this policy group belongs to.

data.relationships.account.data.type* (string)

Available values: accounts

data.relationships.account.data.id* (string)

data.relationships.vcs-provider* (object)

The policy group’s VCS provider.

data.relationships.vcs-provider.data.type* (string)

Available values: vcs-providers

data.relationships.vcs-provider.data.id* (string)

Example Request:

PATCH /api/iacp/v3/policy-groups/{policy_group} HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
    "data": {
        "attributes": {
            "name": "string",
            "opa-version": "string",
            "vcs-repo": {
                "branch": "string",
                "identifier": "string",
                "path": "string"
            }
        },
        "id": "string",
        "relationships": {
            "account": {
                "data": {
                    "id": "string",
                    "type": "accounts"
                }
            },
            "vcs-provider": {
                "data": {
                    "id": "string",
                    "type": "vcs-providers"
                }
            }
        },
        "type": "policy-groups"
    }
}
Status Codes

  • 200 OK – Success.

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Policy group or relationship not found, or user unauthorized to perform action.

  • 422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).

  • 4XX – Client error.

  • 5XX – Server error.