# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mnx.io/cloudapi/api-details/users.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.