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": "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)

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": "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)

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=bob@test.joyent.com --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": "varth@example.com",
  "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": "varth@example.com",
  "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": "varth@example.com",
  "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": "varth@example.com",
  "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
PreviousKeysNextImages

Last updated