Roles

The Role resource

A collection of permissions that can be assigned to a user, team, or service account via an access policy.

Key path

Description

type* (string)

Available values: roles

id (string)

attributes.description (string)

The description of the role.

attributes.is-system (boolean)

When true the role is built-in, and cannot be modified or deleted.

attributes.name* (string)

The name of the role.

relationships.account (object)

The account this role belongs to.

relationships.account.data.type* (string)

Available values: accounts

relationships.account.data.id* (string)

relationships.permissions (object)

The collection of permissions

relationships.permissions.data* (array)

links.self (string)

List Roles

GET /api/iacp/v3/roles

This endpoint returns a list of IAM roles.

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

  • page[size] (string) – Page size

  • filter[account] (string) – The account filter.

  • filter[role] (string) – The role filter.

  • filter[role][name] (string) – The role name filter.

  • include (array) – The comma-separated list of relationship paths. (Available values: account, permissions)

  • query (string) – Query string

Example Request:

GET /api/iacp/v3/roles 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 a Role

POST /api/iacp/v3/roles

Create a new IAM role.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: account, permissions)

Request body:

Key path

Description

data.type* (string)

Available values: roles

data.id (string)

data.attributes.description (string)

The description of the role.

data.attributes.name* (string)

The name of the role.

data.relationships.account (object)

The account this role belongs to.

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

Available values: accounts

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

data.relationships.permissions (object)

The collection of permissions

data.relationships.permissions.data* (array)

Example Request:

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

{
  "data": {
    "type": "roles",
    "attributes": {
      "description": "Workspace full access",
      "name": "workspace-admin"
    },
    "relationships": {
      "permissions": {
        "data": [
          {
            "type": "permissions",
            "id": "workspaces:create"
          },
          {
            "type": "permissions",
            "id": "workspaces:delete"
          },
          {
            "type": "permissions",
            "id": "workspaces:read"
          },
          {
            "type": "permissions",
            "id": "workspaces:set-access-policies"
          },
          {
            "type": "permissions",
            "id": "workspaces:update"
          }
        ]
      },
      "account": {
        "data": {
          "type": "accounts",
          "id": "acc-svrcncgh453bi8g"
        }
      }
    }
  }
}
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": {
          "description": "Workspace full access",
          "is-system": false,
          "name": "workspace-admin"
        },
        "id": "role-thjhle31nfrmujg",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/roles/role-thjhle31nfrmujg"
        },
        "relationships": {
          "account": {
            "data": {
              "id": "acc-svrcncgh453bi8g",
              "type": "accounts"
            }
          },
          "permissions": {
            "data": [
              {
                "id": "workspaces:create",
                "type": "permissions"
              },
              {
                "id": "workspaces:delete",
                "type": "permissions"
              },
              {
                "id": "workspaces:read",
                "type": "permissions"
              },
              {
                "id": "workspaces:set-access-policies",
                "type": "permissions"
              },
              {
                "id": "workspaces:update",
                "type": "permissions"
              }
            ]
          }
        },
        "type": "roles"
      },
      "included": null,
      "meta": null
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Account not found or user unauthorized.

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

  • 4XX – Client error.

  • 5XX – Server error.

Delete a Role

DELETE /api/iacp/v3/roles/{role}

The endpoint deletes IAM role by ID.

Parameters
  • role (string) –

Status Codes

Get a Role

GET /api/iacp/v3/roles/{role}

The endpoint returns an IAM role by ID.

Parameters
  • role (string) – The ID of the role.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: account, permissions)

Example Request:

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

Update a Role

PATCH /api/iacp/v3/roles/{role}

This endpoint updates IAM role by ID.

Parameters
  • role (string) – The ID of the role to update.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: account, permissions)

Request body:

Key path

Description

data.type* (string)

Available values: roles

data.id (string)

data.attributes.description (string)

The description of the role.

data.attributes.name* (string)

The name of the role.

data.relationships.account (object)

The account this role belongs to.

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

Available values: accounts

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

data.relationships.permissions (object)

The collection of permissions

data.relationships.permissions.data* (array)

Example Request:

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

{
    "data": {
        "attributes": {
            "description": "string",
            "name": "string"
        },
        "id": "string",
        "relationships": {
            "account": {
                "data": {
                    "id": "string",
                    "type": "accounts"
                }
            },
            "permissions": {
                "data": [
                    {
                        "id": "string",
                        "type": "permissions"
                    }
                ]
            }
        },
        "type": "roles"
    }
}
Status Codes