Teams

The Team resource

A IAM team is used to organize users into logical units.

A team can not be used to group service accounts, only standard users.

Key path

Description

type* (string)

Available values: teams

id (string)

attributes.description (string)

The verbose description of the team.

attributes.name* (string)

The name of the team.

relationships.account (object)

The account this team belongs to.

relationships.account.data.type* (string)

Available values: accounts

relationships.account.data.id* (string)

relationships.identity-provider (object)

Identity provider of the team. Can be internal (Scalr) or external (LDAP/SAML)

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

Available values: identity-providers

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

relationships.users (object)

The list of users in the team.

relationships.users.data* (array)

links.self (string)

List Teams

GET /api/iacp/v3/teams

The endpoint returns a list of IAM teams. To list teams for a specific account, the filter[account] filter can be used. The endpoint supports filtering by team name (filter[name]), IdP (filter[identity-provider]) and team ID (filter[team]=in:team-123,team-331).

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

  • page[size] (string) – Page size

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

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

  • filter[identity-provider] (string) – The identity provider filter.

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

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

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

  • query (string) – Query string

Example Request:

GET /api/iacp/v3/teams 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": {
            "description": null,
            "name": "Users"
          },
          "id": "team-t67mjto75maj8p0",
          "links": {
            "self": "https://my.scalr.io/api/iacp/v3/teams/team-t67mjto75maj8p0"
          },
          "relationships": {
            "account": null,
            "identity-provider": {
              "data": {
                "id": "idp-sojhv9e9tfhao3g",
                "type": "identity-providers"
              }
            },
            "users": null
          },
          "type": "teams"
        },
        {
          "attributes": {
            "description": "Global admins",
            "name": "Admins"
          },
          "id": "team-t67mjto46ev8i38",
          "links": {
            "self": "https://my.scalr.io/api/iacp/v3/teams/team-t67mjto46ev8i38"
          },
          "relationships": {
            "account": null,
            "identity-provider": {
              "data": {
                "id": "idp-sojhv9e9tfhao3g",
                "type": "identity-providers"
              }
            },
            "users": {
              "data": [
                {
                  "id": "user-suh84u730af2bm0",
                  "type": "users"
                }
              ]
            }
          },
          "type": "teams"
        },
        {
          "attributes": {
            "description": null,
            "name": "Users"
          },
          "id": "team-t67mjtnokncjpd8",
          "links": {
            "self": "https://my.scalr.io/api/iacp/v3/teams/team-t67mjtnokncjpd8"
          },
          "relationships": {
            "account": {
              "data": {
                "id": "acc-svrcncgh453bi8g",
                "type": "accounts"
              }
            },
            "identity-provider": {
              "data": {
                "id": "idp-sohkb0o1phrdmr8",
                "type": "identity-providers"
              }
            },
            "users": {
              "data": [
                {
                  "id": "user-suh84u6vuvidtbg",
                  "type": "users"
                },
                {
                  "id": "user-suh84u72gfrbd30",
                  "type": "users"
                }
              ]
            }
          },
          "type": "teams"
        },
        {"...": "..."}
      ],
      "included": null,
      "links": {
        "first": "https://my.scalr.io/api/iacp/v3/teams?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "last": "https://my.scalr.io/api/iacp/v3/teams?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "next": null,
        "prev": null,
        "self": "https://my.scalr.io/api/iacp/v3/teams?page%5Bnumber%5D=1&page%5Bsize%5D=20"
      },
      "meta": {
        "pagination": {
          "current-page": 1,
          "next-page": null,
          "prev-page": null,
          "total-count": 5,
          "total-pages": 1
        }
      }
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 4XX – Client error.

  • 5XX – Server error.

Create a Team

POST /api/iacp/v3/teams

The endpoint creates an IAM team. If an external IdP used, the team name must exist in that IdP.

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

Request body:

Key path

Description

data.type* (string)

Available values: teams

data.id (string)

data.attributes.description (string)

The verbose description of the team.

data.attributes.name* (string)

The name of the team.

data.relationships.account (object)

The account this team belongs to.

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

Available values: accounts

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

data.relationships.identity-provider (object)

Identity provider of the team. Can be internal (Scalr) or external (LDAP/SAML)

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

Available values: identity-providers

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

data.relationships.users (object)

The list of users in the team.

data.relationships.users.data* (array)

Example Request:

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

{
  "data": {
    "attributes": {
      "description": null,
      "name": "team4"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "acc-svrcncgh453bi8g",
          "type": "accounts"
        }
      },
      "identity-provider": {
        "data": {
          "id": "idp-sohkb0o1phrdmr8",
          "type": "identity-providers"
        }
      },
      "users": {
        "data": [
          {
            "id": "user-suh84u70pjo994o",
            "type": "users"
          }
        ]
      }
    },
    "type": "teams"
    }
}
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":"",
          "name":"team4"
        },
        "id":"team-tjumhdrhf3gk2io",
        "links":{
          "self":"https://my.scalr.io/api/iacp/v3/teams/team-tjumhdrhf3gk2io"
        },
        "relationships":{
          "account": {
            "data": {
              "id": "acc-svrcncgh453bi8g",
              "type": "accounts"
            },
          },
          "identity-provider":{
            "data":{
              "id":"idp-sohkb0o1phrdmr8",
              "type":"identity-providers"
            }
          },
          "users":{
            "data":[
              {
                "id":"user-suh84u70pjo994o",
                "type":"users"
              }
            ]
          }
        },
        "type":"teams"
      },
      "included": null,
      "meta":null
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Relationship not found or user is not authorized 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 a Team

DELETE /api/iacp/v3/teams/{team}

The endpoint deletes IAM team by ID.

Parameters
  • team (string) –

Status Codes

Get a Team

GET /api/iacp/v3/teams/{team}

This endpoint returns an IAM team by ID.

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

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

Example Request:

GET /api/iacp/v3/teams/{team} 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": {
          "description": null,
          "name": "Users"
        },
        "id": "team-t67mjtnokncjpd8",
        "links": {
          "self": "https://my.scalr.io/api/iacp/v3/teams/team-t67mjtnokncjpd8"
        },
        "relationships": {
          "account": {
            "data": {
              "id": "acc-svrcncgh453bi8g",
              "type": "accounts"
            }
          },
          "identity-provider": {
            "data": {
              "id": "idp-sohkb0o1phrdmr8",
              "type": "identity-providers"
            }
          },
          "users": {
            "data": [
              {
                "id": "user-suh84u6vuvidtbg",
                "type": "users"
              },
              {
                "id": "user-suh84u72gfrbd30",
                "type": "users"
              }
            ]
          }
        },
        "type": "teams"
      },
      "included": null,
      "meta": null
    }
    

  • 403 Forbidden – User unauthorized to perform this action.

  • 404 Not Found – Team not found.

  • 4XX – Client error.

  • 5XX – Server error.

Update a Team

PATCH /api/iacp/v3/teams/{team}

Update a team’s attributes or users. The endpoint can be used to add or remove users from a team.

Parameters
  • team (string) –

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

Request body:

Key path

Description

data.type* (string)

Available values: teams

data.id (string)

data.attributes.description (string)

The verbose description of the team.

data.attributes.name* (string)

The name of the team.

data.relationships.account (object)

The account this team belongs to.

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

Available values: accounts

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

data.relationships.identity-provider (object)

Identity provider of the team. Can be internal (Scalr) or external (LDAP/SAML)

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

Available values: identity-providers

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

data.relationships.users (object)

The list of users in the team.

data.relationships.users.data* (array)

Example Request:

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

{
  "data": {
    "attributes": {
      "description": "Some description",
      "name": "team4"
    },
    "relationships": {
      "users": {
        "data": [
          {
            "id": "user-suh84u70pjo994o",
            "type": "users"
          }
        ]
      }
    },
    "type": "teams"
    }
}
Status Codes
  • 200 OK

    Successfully updated.

    Example Respone:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    Preference-Applied: profile=preview
    
    {
      "data":{
        "attributes":{
          "description":"Some description",
          "name":"team4"
        },
        "id":"team-tjumhdrhf3gk2io",
        "links":{
          "self":"https://my.scalr.io/api/iacp/v3/teams/team-tjumhdrhf3gk2io"
        },
        "relationships":{
          "account": {
            "data": {
              "id": "acc-svrcncgh453bi8g",
              "type": "accounts"
            },
          },
          "identity-provider":{
            "data":{
              "id":"idp-sohkb0o1phrdmr8",
              "type":"identity-providers"
            }
          },
          "users":{
            "data":[
              {
                "id":"user-suh84u70pjo994o",
                "type":"users"
              }
            ]
          }
        },
        "type":"teams"
      },
      "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.