Access Policies

The AccessPolicy resource

Grants the permissions declared in a role to a user, team, or service account.

An access policy is applied to an environment or a specific workspace.

Key path

Description

type* (string)

Available values: access-policies

id (string)

attributes.is-system (boolean)

The access policy is a built-in read-only policy that cannot be updated or deleted.

relationships.account (object)

Grant access to the account and to all environments and workspaces in the account.

relationships.account.data.type* (string)

Available values: accounts

relationships.account.data.id* (string)

relationships.environment (object)

Grant access to the environment and all workspaces within it.

relationships.environment.data.type* (string)

Available values: environments

relationships.environment.data.id* (string)

relationships.roles* (object)

The roles with permissions.

relationships.roles.data* (array)

relationships.service-account (object)

Role binding to a service account.

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

Available values: service-accounts

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

relationships.team (object)

Role binding to a team.

relationships.team.data.type* (string)

Available values: teams

relationships.team.data.id* (string)

relationships.user (object)

Role binding to a user.

relationships.user.data.type* (string)

Available values: users

relationships.user.data.id* (string)

relationships.workspace (object)

Grant access to the workspace.

relationships.workspace.data.type* (string)

Available values: workspaces

relationships.workspace.data.id* (string)

links (object)

List Access Policies

GET /api/iacp/v3/access-policies

This endpoint returns a list of IAM access policies.

Query Parameters
  • page[number] (string) – Page number

  • page[size] (string) – Page size

  • filter[account] (string) – Account filter

  • filter[access-policy] (string) – Access Policy filter.

  • filter[environment] (string) – Environment filter

  • filter[workspace] (string) – Workspace filter

  • filter[user] (string) – User filter

  • filter[team] (string) – Team filter

  • filter[service-account] (string) – Service account filter

  • query (string) – Query string

  • sort (array) – The comma-separated list of attributes. (Available values: account, environment, service-account, team, user, workspace)

  • include (array) – The comma-separated list of relationship paths. (Available values: account, environment, roles, service-account, team, user, workspace)

Example Request:

GET /api/iacp/v3/access-policies HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK – Success.

  • 403 Forbidden – User unauthorized to perform this action.

  • 4XX – Client error.

  • 5XX – Server error.

Create an Access Policy

POST /api/iacp/v3/access-policies

Grant access for a member identity to a scope identity.

Access is a set of roles. Member identity might be one of user, team, or service-account. Scope identity is one of account, environment, or workspace.

Check out identity and access management for a detailed description of the Scalr IAM model.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: account, environment, roles, service-account, team, user, workspace)

Request body:

Key path

Description

data.type* (string)

Available values: access-policies

data.id (string)

data.relationships.account (object)

Grant access to the account and to all environments and workspaces in the account.

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

Available values: accounts

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

data.relationships.environment (object)

Grant access to the environment and all workspaces within it.

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

Available values: environments

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

data.relationships.roles* (object)

The roles with permissions.

data.relationships.roles.data* (array)

data.relationships.service-account (object)

Role binding to a service account.

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

Available values: service-accounts

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

data.relationships.team (object)

Role binding to a team.

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

Available values: teams

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

data.relationships.user (object)

Role binding to a user.

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

Available values: users

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

data.relationships.workspace (object)

Grant access to the workspace.

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

Available values: workspaces

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

data.links (object)

Example Request:

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

{
  "data": {
    "type": "access-policies",
    "attributes": {},
    "relationships": {
      "roles": {
        "data": [
          {
            "type": "roles",
            "id": "role-thjhle31nfrmujg"
          },
          {
            "type": "roles",
            "id": "role-t67mjtmdvap7s28"
          },
          {
            "type": "roles",
            "id": "role-t67mjtmd93j62hg"
          }
        ]
      },
      "account": {
        "data": {
          "type": "accounts",
          "id": "acc-svrcncgh453bi8g"
        }
      },
      "user": {
        "data": {
          "type": "users",
          "id": "user-suh84u6vuvidtbg"
        }
      }
    }
  }
}
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": {
          "is-system": false
        },
        "id": "ap-thji3qhu78kvsm8",
        "links": null,
        "relationships": {
          "account": {
            "data": {
              "id": "acc-svrcncgh453bi8g",
              "type": "accounts"
            }
          },
          "environment": null,
          "roles": {
            "data": [
              {
                "id": "role-t67mjtmd93j62hg",
                "type": "roles"
              },
              {
                "id": "role-t67mjtmdvap7s28",
                "type": "roles"
              },
              {
                "id": "role-thjhle31nfrmujg",
                "type": "roles"
              }
            ]
          },
          "service-account": null,
          "team": null,
          "user": {
            "data": {
              "id": "user-suh84u6vuvidtbg",
              "type": "users"
            }
          },
          "workspace": null
        },
        "type": "access-policies"
      },
      "included": null,
      "meta": null
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Relationship not found or user unauthorized to read it.

  • 409 Conflict – Quota exceeded error.

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

  • 4XX – Client error.

  • 5XX – Server error.

Delete Access Policy

DELETE /api/iacp/v3/access-policies/{access_policy}
Parameters
  • access_policy (string) – The ID of the access policy to delete.

Status Codes

Get an Access Policy

GET /api/iacp/v3/access-policies/{access_policy}

The endpoint returns IAM access policy by ID.

Parameters
  • access_policy (string) – The ID of the access policy.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: account, environment, roles, service-account, team, user, workspace)

Example Request:

GET /api/iacp/v3/access-policies/{access_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 – Access policy not found.

  • 4XX – Client error.

  • 5XX – Server error.

Update an Access Policy

PATCH /api/iacp/v3/access-policies/{access_policy}
Parameters
  • access_policy (string) – The ID of the access policy to update.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: account, environment, roles, service-account, team, user, workspace)

Request body:

Key path

Description

data.type* (string)

Available values: access-policies

data.id (string)

data.relationships.account (object)

Grant access to the account and to all environments and workspaces in the account.

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

Available values: accounts

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

data.relationships.environment (object)

Grant access to the environment and all workspaces within it.

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

Available values: environments

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

data.relationships.roles* (object)

The roles with permissions.

data.relationships.roles.data* (array)

data.relationships.service-account (object)

Role binding to a service account.

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

Available values: service-accounts

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

data.relationships.team (object)

Role binding to a team.

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

Available values: teams

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

data.relationships.user (object)

Role binding to a user.

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

Available values: users

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

data.relationships.workspace (object)

Grant access to the workspace.

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

Available values: workspaces

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

data.links (object)

Example Request:

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

{
    "data": {
        "id": "string",
        "links": {},
        "relationships": {
            "account": {
                "data": {
                    "id": "string",
                    "type": "accounts"
                }
            },
            "environment": {
                "data": {
                    "id": "string",
                    "type": "environments"
                }
            },
            "roles": {
                "data": [
                    {
                        "id": "string",
                        "type": "roles"
                    }
                ]
            },
            "service-account": {
                "data": {
                    "id": "string",
                    "type": "service-accounts"
                }
            },
            "team": {
                "data": {
                    "id": "string",
                    "type": "teams"
                }
            },
            "user": {
                "data": {
                    "id": "string",
                    "type": "users"
                }
            },
            "workspace": {
                "data": {
                    "id": "string",
                    "type": "workspaces"
                }
            }
        },
        "type": "access-policies"
    }
}
Status Codes