Users¶

The User resource¶

Represents a Scalr IAM user.

Key path

Description

type* (string)

Available values: users

id (string)

attributes.created-at (string)

attributes.email* (string)

attributes.full-name (string)

attributes.last-login-at (string)

attributes.status (string)

Available values: Active, Inactive, Pending

attributes.username (string)

relationships.identity-providers.data* (array)

relationships.teams.data* (array)

links.self (string)

Invite a User to the Account¶

POST /api/iacp/v3/accounts/{account}/actions/invite¶

Invite the user to the account by adding it to the account teams and/or creating access policies within the account.

If the user with a specified email does not exist - a new one will be created. The new user will be in the ‘pending’ status until the first login to the account.

This is the preferred way to create users.

Parameters

account (string) –

Query Parameters

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

Request body:

Key path	Description
data.type* (string) Available values: `users`
data.id (string)
data.attributes.email* (string)
data.attributes.send-invite (boolean)	If set to `true`, email with invite to the account will be sent to the user email.
data.relationships.roles (object)	Assign roles for this user on the account scope.
data.relationships.roles.data* (array)
data.relationships.teams (object)	Add user to the teams.
data.relationships.teams.data* (array)
data.links (object)

Example Request:

POST /api/iacp/v3/accounts/{account}/actions/invite HTTP/1.1
Host: my.scalr.io
Content-Type: application/vnd.api+json
Prefer: profile=preview

{
  "data":{
    "type":"users",
    "attributes":{
      "email":"[email protected]",
      "send-invite":false
    },
    "relationships":{
      "teams":{
        "data":[
          {
            "type":"teams",
            "id":"team-t67mjtnokncjpd8"
          }
        ]
      },
      "roles":{
        "data":[
          {
            "type":"roles",
            "id":"role-t67mjtmauajto7g"
          },
          {
            "type":"roles",
            "id":"role-t67mjtmd93j62hg"
          }
        ]
      }
    }
  }
}

Status Codes

201 Created –

Success.

Example Respone:

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

{
  "data":{
    "attributes":{
      "status":"Pending"
    },
    "id":"24429152-fced-6c00-9ad6-374b648d166b",
    "links":{},
    "relationships":{
      "account":{
        "data":{
          "id":"acc-svrcncgh453bi8g",
          "type":"accounts"
        }
      },
      "teams":{
        "data":[
          {
            "id":"team-t67mjtnokncjpd8",
            "type":"teams"
          }
        ]
      },
      "user":{
        "data":{
          "id":"user-tmh3n6qao207cdg",
          "type":"users"
        }
      }
    },
    "type":"account-users"
  },
  "included":null,
  "meta":null
}

403 Forbidden – User unauthorized to perform this action.
404 Not Found – User, Account, not found.
422 Unprocessable Entity – Invalid team or role.
4XX – Client error.
5XX – Server error.

Remove a User from the Account¶

DELETE /api/iacp/v3/accounts/{account}/actions/remove/{user}¶

The endpoint removes all user access policies and team bindings associated with the account.

Parameters

account (string) – The ID of the account.
user (string) – The ID of the user.

Status Codes

204 No Content – Successfully removed.
403 Forbidden – User unauthorized to perform this action.
404 Not Found – The user or account not found.
4XX – Client error.
5XX – Server error.

List Users¶

GET /api/iacp/v3/users¶

This endpoint returns a list of IAM users. The response can be filtered by IdP: filter[identity-provider] or user ID: filter[user].

Query Parameters

page[number] (string) – Page number
page[size] (string) – Page size
filter[identity-provider] (string) – The identity provider filter.
filter[user] (string) – User filter.
filter[email] (string) – Email filter.
include (array) – The comma-separated list of relationship paths. (Available values: identity-providers, teams)
sort (array) – The comma-separated list of attributes. (Available values: created-at, email, full-name, last-login-at, status)
query (string) – Query string

Example Request:

GET /api/iacp/v3/users 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": {
        "created-at": "2021-09-29T22:00:29Z",
        "email": "[email protected]",
        "full-name": "",
        "iam-type": "TeamUser",
        "last-login-at": null,
        "status": "Active",
        "username": "[email protected]"
      },
      "id": "user-tmg3nenau6j3ngg",
      "links": {
        "self": "https://my.scalr.io/api/iacp/v3/users/user-tmg3nenau6j3ngg"
      },
      "relationships": {
        "identity-providers": null,
        "teams": null
      },
      "type": "users"
    },
    {
      "attributes": {
        "created-at": "2020-02-13T14:55:10Z",
        "email": "[email protected]",
        "full-name": "produser1",
        "iam-type": "AccountOwner",
        "last-login-at": "2020-10-14T13:44:58Z",
        "status": "Active",
        "username": "[email protected]"
      },
      "id": "user-suh84u72qsmbuvg",
      "links": {
        "self": "https://my.scalr.io/api/iacp/v3/users/user-suh84u72qsmbuvg"
      },
      "relationships": {
        "identity-providers": {
          "data": [
            {
              "id": "idp-sojhv9e8mc2k808",
              "type": "identity-providers"
            }
          ]
        },
        "teams": {
          "data": [
            {
              "id": "team-t67mjto1k4vjptg",
              "type": "teams"
            }
          ]
        }
      },
      "type": "users"
    },
    {"...": "..."}
  ],
  "included": null,
  "links": {
    "first": "https://my.scalr.io/api/iacp/v3/users?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "last": "https://my.scalr.io/api/iacp/v3/users?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "next": "https://my.scalr.io/api/iacp/v3/users?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "prev": null,
    "self": "https://my.scalr.io/api/iacp/v3/users?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "next-page": 2,
      "prev-page": null,
      "total-count": 24,
      "total-pages": 2
    }
  }
}

403 Forbidden – User unauthorized to perform this action.
4XX – Client error.
5XX – Server error.

Create a User¶

POST /api/iacp/v3/users¶

Create a new IAM user without access to any account. To invite user to the account /accounts/:id/actions/invite should be used.

Query Parameters

include (array) – The comma-separated list of relationship paths. (Available values: identity-providers)

Request body:

Key path	Description
data.type* (string) Available values: `users`
data.id (string)
data.attributes.change-password-on-sign-in (boolean)	If set to `true`, the user will be asked to change the temporary password on the first sign in.
data.attributes.created-at (string)
data.attributes.email* (string)
data.attributes.full-name (string)
data.attributes.password (string)	Must be at least 8 characters long and contain at least one digit, one lowercase letter, one uppercase letter, and one special character.
data.attributes.status (string) Available values: `Active`, `Inactive`, `Pending`	User status. Can be: `Active`, `Inactive`, `Pending`. Pending user will be activated after the first sign in.
data.relationships.identity-providers.data* (array)

Example Request:

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

{
  "data": {
    "type": "users",
    "attributes": {
      "email": "[email protected]",
      "full-name": "",
      "status": "Active",
      "change-password-on-sign-in": true,
      "password": ""
    },
    "relationships": {}
  }
}

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": {
      "change-password-on-sign-in": true,
      "created-at": "2021-09-20T12:48:52Z",
      "email": "[email protected]",
      "full-name": "",
      "password": "**************",
      "status": "Active"
    },
    "id": "user-tm10gkj2sju4l50",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/users/user-tmg3q1oanl65tho"
    },
    "relationships": {
      "identity-providers": null
    },
    "type": "users"
  },
  "included": null,
  "meta": null
}

403 Forbidden – User unauthorized to perform this action.
404 Not Found – Relationship not found or user unauthorized.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.

Delete a User¶

DELETE /api/iacp/v3/users/{user}¶

The endpoint deletes IAM user by ID.

Parameters

user (string) – The ID of the user to delete.

Status Codes

204 No Content – Successfully deleted.
403 Forbidden – User unauthorized to perform this action.
404 Not Found – User not found.
4XX – Client error.
5XX – Server error.

Get a User¶

GET /api/iacp/v3/users/{user}¶

This endpoint returns an IAM user by ID.

Parameters

user (string) – The ID of the user.

Query Parameters

include (array) – The comma-separated list of relationship paths. (Available values: identity-providers, teams)

Example Request:

GET /api/iacp/v3/users/{user} 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": {
      "created-at": "2021-09-29T22:02:45Z",
      "email": "[email protected]",
      "full-name": "",
      "iam-type": "TeamUser",
      "last-login-at": null,
      "status": "Active",
      "username": "[email protected]"
    },
    "id": "user-tmg3q1oanl65tho",
    "links": {
      "self": "https://my.scalr.io/api/iacp/v3/users/user-tmg3q1oanl65tho"
    },
    "relationships": {
      "identity-providers": null,
      "teams": null
    },
    "type": "users"
  },
  "included": null,
  "meta": null
}

403 Forbidden – User unauthorized to perform this action.
404 Not Found – User not found.
4XX – Client error.
5XX – Server error.

Update a User¶

PATCH /api/iacp/v3/users/{user}¶

This endpoint updates IAM user by ID.

Parameters

user (string) – The ID of the user to update.

Query Parameters

include (array) – The comma-separated list of relationship paths. (Available values: identity-providers, teams)

Request body:

Key path	Description
data.type* (string) Available values: `users`
data.id (string)
data.attributes.created-at (string)
data.attributes.email* (string)
data.attributes.full-name (string)
data.attributes.last-login-at (string)
data.attributes.status (string) Available values: `Active`, `Inactive`, `Pending`
data.attributes.username (string)
data.relationships.identity-providers.data* (array)
data.relationships.teams.data* (array)

Example Request:

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

{
  "data":{
    "type":"users",
    "attributes":{
      "full-name":"Test User"
    },
    "relationships":{

    }
  }
}

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":{
      "created-at":"2021-09-30T12:55:03Z",
      "email":"[email protected]",
      "full-name":"Test User",
      "last-login-at":null,
      "status":"Active",
      "username":"[email protected]m"
    },
    "id":"user-tmh3n6qao207cdg",
    "links":{
      "self":"https://my.scalr.io/api/iacp/v3/users/user-tmh3n6qao207cdg"
    },
    "relationships":{
      "identity-providers":null,
      "teams":{
        "data":[
          {
            "id":"team-t67mjtnokncjpd8",
            "type":"teams"
          }
        ]
      }
    },
    "type":"users"
  },
  "included":null,
  "meta":null
}

403 Forbidden – User unauthorized to perform this action.
404 Not Found – User not found.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.