> For the complete documentation index, see [llms.txt](https://docs.mnx.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mnx.io/cloudapi/api-details/users.md).

# Users

### ListUsers (GET /:account/users) <a href="#listusers" id="listusers"></a>

Returns a list of an account's user objects. These have the same format as the main [account](https://apidocs.joyent.com/cloudapi/#account) object.

#### Inputs <a href="#inputs-8" id="inputs-8"></a>

* None

#### Returns <a href="#returns-8" id="returns-8"></a>

Array of user objects. Each user object has the following fields:

| **Field**   | **Type**     | **Description**                           |
| ----------- | ------------ | ----------------------------------------- |
| id          | UUID         | Unique id for this user                   |
| login       | String       | Sub-user login name                       |
| email       | String       | Email address                             |
| companyName | String       | ...                                       |
| firstName   | String       | ...                                       |
| lastName    | String       | ...                                       |
| address     | String       | ...                                       |
| postalCode  | String       | ...                                       |
| city        | String       | ...                                       |
| state       | String       | ...                                       |
| country     | String       | ...                                       |
| phone       | String       | ...                                       |
| created     | ISO8601 date | When this user was created                |
| updated     | ISO8601 date | When this user's details was last updated |

#### Errors <a href="#errors-8" id="errors-8"></a>

| **Error Code**   | **Description**              |
| ---------------- | ---------------------------- |
| ResourceNotFound | If `:account` does not exist |

#### CLI Command: <a href="#cli-command-7" id="cli-command-7"></a>

```
sdc-user list
```

#### Example Request <a href="#example-request-8" id="example-request-8"></a>

```
GET /my/users HTTP/1.1
Accept: application/json
Host: api.example.com
Api-Version: ~8
Authorization: Signature keyId...
```

#### Example Response <a href="#example-response-8" id="example-response-8"></a>

```
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 503
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: 6csVzj9aNZWB5/ZW9JsD8w==
Date: Wed, 23 Dec 2015 06:42:20 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 50182970-a940-11e5-af28-0b661ec813b9
Response-Time: 1051

[
  {
    "id": "4fc13ac6-1e7d-cd79-f3d2-96276af0d638",
    "login": "barbar",
    "email": "barbar@example.com",
    "companyName": "Example",
    "firstName": "BarBar",
    "lastName": "Jinks",
    "phone": "(123)457-6890",
    "updated": "2015-12-23T06:41:11.032Z",
    "created": "2015-12-23T06:41:11.032Z"
  },
  {
    "id": "332ce629-fcc5-45c3-e34f-e7cfbeab1327",
    "login": "san",
    "email": "san@example.com",
    "companyName": "Example Inc",
    "firstName": "San",
    "lastName": "Holo",
    "phone": "(123)456-0987",
    "updated": "2015-12-23T06:41:56.102Z",
    "created": "2015-12-23T06:41:56.102Z"
  }
]
```

### GetUser (GET /:account/users/:user) <a href="#getuser" id="getuser"></a>

Get one user for an account.

#### Inputs <a href="#inputs-9" id="inputs-9"></a>

| **Field**  | **Type** | **Description**                                  |
| ---------- | -------- | ------------------------------------------------ |
| membership | Boolean  | When given, the user roles will also be returned |

#### Returns <a href="#returns-9" id="returns-9"></a>

An array of user objects. Each user object has the following fields:

| **Field**      | **Type**     | **Description**                                                              |
| -------------- | ------------ | ---------------------------------------------------------------------------- |
| id             | UUID         | Unique id for this user                                                      |
| login          | String       | Sub-user login name                                                          |
| email          | String       | Email address                                                                |
| companyName    | String       | ...                                                                          |
| firstName      | String       | ...                                                                          |
| lastName       | String       | ...                                                                          |
| address        | String       | ...                                                                          |
| postalCode     | String       | ...                                                                          |
| city           | String       | ...                                                                          |
| state          | String       | ...                                                                          |
| country        | String       | ...                                                                          |
| phone          | String       | ...                                                                          |
| roles          | Array        | User role names (only when `membership` option is present in request)        |
| default\_roles | Array        | User active role names (only when `membership` option is present in request) |
| created        | ISO8601 date | When this user was created                                                   |
| updated        | ISO8601 date | When this user's details was last updated                                    |

#### Errors <a href="#errors-9" id="errors-9"></a>

| **Error Code**   | **Description**                         |
| ---------------- | --------------------------------------- |
| ResourceNotFound | When `:account` or `:user` do not exist |

#### CLI Command: <a href="#cli-command-8" id="cli-command-8"></a>

```
sdc-user get 4fc13ac6-1e7d-cd79-f3d2-96276af0d638
```

#### Example Request <a href="#example-request-9" id="example-request-9"></a>

```
GET /my/users/4fc13ac6-1e7d-cd79-f3d2-96276af0d638 HTTP/1.1
Accept: application/json
Host: api.example.com
Api-Version: ~8
Authorization: Signature keyId...
```

#### Example Response <a href="#example-response-9" id="example-response-9"></a>

```
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 253
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET, HEAD, POST, DELETE
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: p4/N2pQwLkNuvKTjaKJPOw==
Date: Wed, 23 Dec 2015 07:07:44 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: dc761fa0-a943-11e5-842f-87950f2a2edd
Response-Time: 961

{
  "id": "4fc13ac6-1e7d-cd79-f3d2-96276af0d638",
  "login": "barbar",
  "email": "barbar@example.com",
  "companyName": "Example",
  "firstName": "BarBar",
  "lastName": "Jinks",
  "phone": "(123)457-6890",
  "updated": "2015-12-23T06:41:11.032Z",
  "created": "2015-12-23T06:41:11.032Z"
}
```

### CreateUser (POST /:account/users) <a href="#createuser" id="createuser"></a>

Creates a new user under an account.

#### Inputs <a href="#inputs-10" id="inputs-10"></a>

| **Field**   | **Type** | **Description**          |
| ----------- | -------- | ------------------------ |
| email       | String   | (Required) Email address |
| login       | String   | (Required) Login         |
| password    | String   | (Required) Password      |
| companyName | String   | ...                      |
| firstName   | String   | ...                      |
| lastName    | String   | ...                      |
| address     | String   | ...                      |
| postalCode  | String   | ...                      |
| city        | String   | ...                      |
| state       | String   | ...                      |
| country     | String   | ...                      |
| phone       | String   | ...                      |

#### Returns <a href="#returns-10" id="returns-10"></a>

User object:

| **Field**   | **Type**     | **Description**                           |
| ----------- | ------------ | ----------------------------------------- |
| id          | UUID         | Unique id for this user                   |
| login       | String       | Sub-user `login` name                     |
| email       | String       | Email address                             |
| companyName | String       | ...                                       |
| firstName   | String       | ...                                       |
| lastName    | String       | ...                                       |
| address     | String       | ...                                       |
| postalCode  | String       | ...                                       |
| city        | String       | ...                                       |
| state       | String       | ...                                       |
| country     | String       | ...                                       |
| phone       | String       | ...                                       |
| created     | ISO8601 date | When this user was created                |
| updated     | ISO8601 date | When this user's details was last updated |

#### Errors <a href="#errors-10" id="errors-10"></a>

For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).

| **Error Code**   | **Description**                                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| InvalidArgument  | If any of the parameters are invalid, e.g. you try to add a login name already taken by another user of your account |
| MissingParameter | If you didn't send a `login`, `email` or `password`                                                                  |
| ResourceNotFound | If `:account` does not exist                                                                                         |

#### CLI Command: <a href="#cli-command-9" id="cli-command-9"></a>

```
sdc-user create --login=bob --email=bob@test.joyent.com --password=123secret
```

#### Request: <a href="#request" id="request"></a>

```
POST /my/users HTTP/1.1
Host: api.example.com
accept: application/json
content-type: application/json
user-agent: restify/2.6.1 (x64-darwin; v8/3.14.5.9; OpenSSL/1.0.1e) node/0.10.26
accept-version: *
date: Thu, 01 May 2014 15:35:21 GMT
content-length: 79
content-md5: E9EmDJjKXMfIsi2mKbwoZA==

{
  "login": "varth",
  "email": "varth@example.com",
  "password": "123secret"
}
```

#### Response: <a href="#response" id="response"></a>

```
HTTP/1.1 201 Created
Location: /my/users/varth
Content-Type: application/json
Content-Length: 163
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: qC9LnijSqZ1I+zea5GQXvQ==
Date: Wed, 23 Dec 2015 09:42:36 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 7f1193b0-a959-11e5-9cdd-eb0b10bce309
Response-Time: 1229

{
  "id": "b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8",
  "login": "varth",
  "email": "varth@example.com",
  "updated": "2015-12-23T09:42:36.517Z",
  "created": "2015-12-23T09:42:36.517Z"
}
```

### UpdateUser (POST /:account/users/:id) <a href="#updateuser" id="updateuser"></a>

Update a user's modifiable properties.

Note: Password changes are not allowed using this endpoint; there is an additional endpoint ([ChangeUserPassword](https://apidocs.joyent.com/cloudapi/ChangeUserPassword)) for password changes so it can be selectively allowed/disallowed for users using policies.

#### Inputs <a href="#inputs-11" id="inputs-11"></a>

| **Field**   | **Type** | **Description** |
| ----------- | -------- | --------------- |
| login       | String   |                 |
| email       | String   |                 |
| companyName | String   |                 |
| firstName   | String   |                 |
| lastName    | String   |                 |
| address     | String   |                 |
| postalCode  | String   |                 |
| city        | String   |                 |
| state       | String   |                 |
| country     | String   |                 |
| phone       | String   |                 |

#### Returns <a href="#returns-11" id="returns-11"></a>

User object:

| **Field**   | **Type**     | **Description**                           |
| ----------- | ------------ | ----------------------------------------- |
| id          | UUID         | Unique id for this user                   |
| login       | String       | User login name                           |
| email       | String       | Email address                             |
| companyName | String       | ...                                       |
| firstName   | String       | ...                                       |
| lastName    | String       | ...                                       |
| address     | String       | ...                                       |
| postalCode  | String       | ...                                       |
| city        | String       | ...                                       |
| state       | String       | ...                                       |
| country     | String       | ...                                       |
| phone       | String       | ...                                       |
| created     | ISO8601 date | When this user was created                |
| updated     | ISO8601 date | When this user's details was last updated |

#### Errors <a href="#errors-11" id="errors-11"></a>

For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).

| **Error Code**   | **Description**                                                                                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
| InvalidArgument  | If any of the parameters are invalid, e.g. you try to add a `login` name already taken by another user of your account |
| MissingParameter | If you didn't send a `login` or `email`                                                                                |
| ResourceNotFound | If `:account` or `:user` do not exist                                                                                  |

#### CLI Command: <a href="#cli-command-10" id="cli-command-10"></a>

```
sdc-user update b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8 --login=joe
```

#### Request: <a href="#request-2" id="request-2"></a>

```
POST /my/users/b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8 HTTP/1.1
Host: api.example.com
Api-Version: ~8
accept: application/json
content-type: application/json
user-agent: restify/2.6.1 (x64-darwin; v8/3.14.5.9; OpenSSL/1.0.1e) node/0.10.26
date: Thu, 24 Dec 2015 10:30:44 GMT
content-length: 79
content-md5: E9EmDJjKXMfIsi2mKbwoZA==

{
  "login": "joe",
}
```

#### Response: <a href="#response-2" id="response-2"></a>

```
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 161
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET, HEAD, POST, DELETE
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: 4Sn7xQHfoc1+LvLkA2KbNA==
Date: Thu, 24 Dec 2015 10:30:45 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 63a27380-aa29-11e5-ace8-d79496f2469d
Response-Time: 1148

{
  "id": "b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8",
  "login": "joe",
  "email": "varth@example.com",
  "updated": "2015-12-24T10:28:59.634Z",
  "created": "2015-12-23T09:42:36.517Z"
}
```

### ChangeUserPassword (POST /:account/users/:user/change\_password) <a href="#changeuserpassword" id="changeuserpassword"></a>

This is a separate rule for password changes, so different policies can be used for an user trying to modify other data, or only their own password.

#### Inputs <a href="#inputs-12" id="inputs-12"></a>

| **Field**              | **Type** | **Description**              |
| ---------------------- | -------- | ---------------------------- |
| password               | String   | ...                          |
| password\_confirmation | String   | string must match `password` |

#### Returns <a href="#returns-12" id="returns-12"></a>

User object:

| **Field**   | **Type**       | **Description**                           |
| ----------- | -------------- | ----------------------------------------- |
| id          | UUID           | Unique id for the user                    |
| login       | String         | User login name                           |
| email       | String         | Email address                             |
| companyName | String         | ...                                       |
| firstName   | String         | ...                                       |
| lastName    | String         | ...                                       |
| address     | String         | ...                                       |
| postalCode  | String         | ...                                       |
| city        | String         | ...                                       |
| state       | String         | ...                                       |
| country     | String         | ...                                       |
| phone       | String         | ...                                       |
| created     | Date (ISO8601) | When this user was created                |
| updated     | Date (ISO8601) | When this user's details was last updated |

#### Errors <a href="#errors-12" id="errors-12"></a>

For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).

| **Error Code**   | **Description**                                                      |
| ---------------- | -------------------------------------------------------------------- |
| InvalidArgument  | The provided `password` and `password\_confirmation` didn't match    |
| MissingParameter | Either `password` or `password\_confirmation` parameters are missing |
| ResourceNotFound | If `:account` or `:user` do not exist                                |

#### CLI Command: <a href="#cli-command-11" id="cli-command-11"></a>

```
sdc-user change-password b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8 --password=foo123bar --password-confirmation=foo123bar
```

#### Example Request <a href="#example-request-10" id="example-request-10"></a>

```
POST /my/users/b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8/change_password HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api.example.com
Api-Version: ~8
Content-Length: 40
Authorization: Signature keyId...

{
    "password": "foo123bar",
    "password_confirmation": "foo123bar"
}
```

#### Example Response <a href="#example-response-10" id="example-response-10"></a>

```
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 161
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: qU6CaBlWpuehWaj0IdtPCw==
Date: Thu, 24 Dec 2015 10:34:51 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: f6338220-aa29-11e5-8484-a9b10ef4e687
Response-Time: 1297

{
  "id": "b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8",
  "login": "joe",
  "email": "varth@example.com",
  "updated": "2015-12-24T10:34:51.790Z",
  "created": "2015-12-23T09:42:36.517Z"
}
```

### DeleteUser (DELETE /:account/users/:user) <a href="#deleteuser" id="deleteuser"></a>

Remove a user. They will no longer be able to use this API.

#### Inputs <a href="#inputs-13" id="inputs-13"></a>

* None

#### Returns <a href="#returns-13" id="returns-13"></a>

* None

#### Errors <a href="#errors-13" id="errors-13"></a>

For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).

| **Error Code**   | **Description**                                                                                           |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| ResourceNotFound | If `:account` does not exist or there isn't a user with either the `login` or `id` given as `:user` value |

#### CLI Command: <a href="#cli-command-12" id="cli-command-12"></a>

```
sdc-user delete b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8
```

**Example Request**

```
DELETE /my/users/b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8 HTTP/1.1
Host: api.example.com
Accept: application/json
Api-Version: ~8
Content-Length: 0
```

**Example Response**

```
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: GET, HEAD, POST, DELETE
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Thu, 24 Dec 2015 10:36:18 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 29bcb710-aa2a-11e5-b9f6-05ee86f81e61
Response-Time: 997
```