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":"test_user@scalr.com",
      "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

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": "test_user@scalr.com",
            "full-name": "",
            "iam-type": "TeamUser",
            "last-login-at": null,
            "status": "Active",
            "username": "test_user@scalr.com"
          },
          "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": "produser1@scalr.local",
            "full-name": "produser1",
            "iam-type": "AccountOwner",
            "last-login-at": "2020-10-14T13:44:58Z",
            "status": "Active",
            "username": "produser1@scalr.local"
          },
          "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": "test_user@scalr.com",
      "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": "test_user@scalr.com",
          "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

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": "test_user@scalr.com",
          "full-name": "",
          "iam-type": "TeamUser",
          "last-login-at": null,
          "status": "Active",
          "username": "test_user@scalr.com"
        },
        "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":"test_user@scalr.com",
          "full-name":"Test User",
          "last-login-at":null,
          "status":"Active",
          "username":"test_user@scalr.com"
        },
        "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.