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
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
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.