Users

These are users (also known as sub-users); additional users who are authorized to use the same account, but are subject to the RBAC system. See the RBAC section for more details.

ListUsers (GET /:account/users)
Returns a list of an account's user objects. These have the same format as the main account object.
Inputs
None
Returns
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
Error Code
Description
ResourceNotFound
If :account does not exist
CLI Command:
sdc-user list
Example Request
GET /my/users HTTP/1.1
Accept: application/json
Host: api.example.com
Api-Version: ~8
Authorization: Signature keyId...
Example Response
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": "[email protected]",
    "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": "[email protected]",
    "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)
Get one user for an account.
Inputs
Field
Type
Description
membership
Boolean
When given, the user roles will also be returned
Returns
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
Error Code
Description
ResourceNotFound
When :account or :user do not exist
CLI Command:
sdc-user get 4fc13ac6-1e7d-cd79-f3d2-96276af0d638
Example Request
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
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": "[email protected]",
  "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)
Creates a new user under an account.
Inputs
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
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
For all possible errors, see 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:
sdc-user create --login=bob [email protected] --password=123secret
Request:
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": "[email protected]",
  "password": "123secret"
}
Response:
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": "[email protected]",
  "updated": "2015-12-23T09:42:36.517Z",
  "created": "2015-12-23T09:42:36.517Z"
}
UpdateUser (POST /:account/users/:id)
Update a user's modifiable properties.
Note: Password changes are not allowed using this endpoint; there is an additional endpoint (ChangeUserPassword) for password changes so it can be selectively allowed/disallowed for users using policies.
Inputs
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
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
For all possible errors, see 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:
sdc-user update b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8 --login=joe
Request:
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:
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": "[email protected]",
  "updated": "2015-12-24T10:28:59.634Z",
  "created": "2015-12-23T09:42:36.517Z"
}
ChangeUserPassword (POST /:account/users/:user/change_password)
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
Field
Type
Description
password
String
...
password_confirmation
String
string must match password
Returns
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
For all possible errors, see 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:
sdc-user change-password b5c9cf06-b7de-4c11-9b66-8ace6cb92ee8 --password=foo123bar --password-confirmation=foo123bar
Example Request
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
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": "[email protected]",
  "updated": "2015-12-24T10:34:51.790Z",
  "created": "2015-12-23T09:42:36.517Z"
}
DeleteUser (DELETE /:account/users/:user)
Remove a user. They will no longer be able to use this API.
Inputs
None
Returns
None
Errors
For all possible errors, see 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:
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

Keys

Images

Last modified 3yr ago

Error Code	Description
ResourceNotFound	If `:account` does not exist

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

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

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

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

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