Users¶
List Users¶
GET /api/admin/users
Include Unprocessed Usage
You can optionally pass ?include=balance
to see their unprocessed usage. Unprocessed usage is the amount they have accrued that has not yet been sent to your invoice & payment system.
Example
{
"users": [
{
"id": 1,
"fname": "John",
"lname": "Doe",
"email": "j@doe.com",
"active": true,
"is_admin": false,
"api_key": null,
"api_version": 0,
"external_id": null,
"currency": "USD",
"confirmed_at": "2020-06-09T18:51:59.142Z",
"confirmation_sent_at": null,
"last_request_at": "2020-10-15T05:49:16.258Z",
"last_sign_in_at": "2020-10-15T05:08:36.974Z",
"current_sign_in_at": "2020-10-15T05:45:55.042Z",
"sign_in_count": 50,
"reset_password_sent_at": null,
"locked_at": null,
"failed_attempts": 0,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "US",
"vat": null,
"labels": {},
"created_at": "2020-06-09T18:51:59.145Z",
"updated_at": "2020-10-15T05:49:16.139Z",
"security_keys": [],
"billing_plan": {
"id": 1,
"name": "default"
},
"user_group": {
"id": 1,
"name": "default"
},
"external_integrations": [],
"currency_symbol": "$",
"current_sign_in_ip": "127.0.0.1",
"last_sign_in_ip": "127.0.0.1"
}
]
}
View User¶
GET /api/admin/users/{user_id}
Include Unprocessed Usage
You can optionally pass ?include=balance
to see their unprocessed usage. Unprocessed usage is the amount they have accrued that has not yet been sent to your invoice & payment system.
In addition to querying a user by their user_id
, you may also load a user by the following:
Attribute | Query Param | Example |
---|---|---|
email | find_by_email | /api/admin/users/{Base64.encode64('john@doe.com')}?find_by_email=true |
external_id | find_by_external_id | /api/admin/users/{some-external-id}?find_by_external_id=true |
WHMCS Service ID | find_by_label=whmcs_service_id | /api/admin/users/{whmcs-service-id}?find_by_label=whmcs_service_id |
Example
{
"user": {
"id": 13,
"fname": "Jane",
"lname": "Doe",
"email": "jane@email.net",
"phone": "",
"active": true,
"is_admin": false,
"api_key": null,
"api_version": 0,
"external_id": "",
"currency": "USD",
"confirmed_at": "2020-10-15T05:49:07.263Z",
"confirmation_sent_at": null,
"last_request_at": "2021-03-01T23:11:08.172Z",
"last_sign_in_at": "2021-03-01T23:35:20.304Z",
"current_sign_in_at": "2021-03-01T23:35:37.264Z",
"sign_in_count": 102,
"reset_password_sent_at": null,
"locked_at": null,
"failed_attempts": 0,
"address1": "",
"address2": "",
"city": "",
"state": "",
"zip": "",
"country": "US",
"vat": null,
"company_name": "",
"run_rate": "0.0",
"labels": {},
"created_at": "2020-10-15T05:49:07.272Z",
"updated_at": "2021-03-01T23:35:37.265Z",
"security_keys": [],
"billing_plan": {
"id": 1,
"name": "default"
},
"user_group": {
"id": 1,
"name": "default"
},
"external_integrations": [],
"currency_symbol": "$",
"current_sign_in_ip": "127.0.0.1",
"last_sign_in_ip": "127.0.0.1",
"services": {
"deployments": 1,
"containers": 1,
"container_services": 1,
"container_images": 0,
"container_registries": 0,
"dns_zones": 0
}
}
}
Create User¶
POST /api/admin/users
We also have a non-admin endpoint for creating users.
User Email Address | While we require a unique, and valid, email address, you may elect to have it only valid in terms of syntax, not deliverability. If you pass the option "skip_email_confirm": true in your json request, we will set the email as valid and not send a confirmation email. |
External ID | All users have an external_id field, which is also visible in the Administrator. You're able to use this for your integration and store a value to help identify this user in your system. |
Labels | Users have a key value label section that you can use to store additional details about the user. When viewing the user, the field will be labels , however when creating the user, please use the parameter merge_labels . |
Example
{
"user": {
"skip_email_confirm": true, # Optional, otherwise they will get an email asking them to confirm their account.
"external_id": "", # A field you may use for your own purposes to store a unique id
"fname": "", # required
"lname": "", # required
"email": "", # required. Must be unique in our system! If you skip email confirmation, it does not need to be a real email account.
"password": "", # required
"password_confirmation": "", # required
"address1": "",
"address2": "",
"city": "",
"state": "",
"zip": "", # postal code
"country": "",
"phone": "",
"user_group_id": "", # blank will use the default user group.
"merge_labels": [
{
"key": "value"
}
]
}
}
Additional User Fields
Field | Type | Notes |
---|---|---|
active | Boolean | Suspended, or un-suspended |
is_admin | Boolean | Grant admin access to this user |
currency | String | Must be a 3-digit code, like EUR or USD . |
bypass_billing | Boolean | Whether or not billing data should be processed by any billing integration |
company_name | string | |
locale | string | Their language in 2-digit format, examples: en , fr , de . |
Example
{
"id": 100,
"fname": "John",
"lname": "Doe",
"email": "j@doe.local",
"active": true,
"is_admin": false,
"external_id": "",
"currency": "USD",
"confirmed_at": "2020-10-15T05:49:07.263Z",
"confirmation_sent_at": null,
"last_request_at": "2021-03-01T23:11:08.172Z",
"last_sign_in_at": "2021-03-01T22:17:10.344Z",
"current_sign_in_at": "2021-03-01T23:27:37.728Z",
"sign_in_count": 0,
"reset_password_sent_at": null,
"locked_at": null,
"failed_attempts": 0,
"address1": "",
"address2": "",
"city": "",
"state": "",
"zip": "",
"country": "US",
"created_at": "2020-10-15T05:49:07.272Z",
"updated_at": "2021-03-01T23:27:37.729Z",
"security_keys": [],
"billing_plan": {
"id": 1,
"name": "default"
},
"user_group": {
"id": 1,
"name": "default"
},
"external_integrations": [],
"currency_symbol": "$",
"current_sign_in_ip": "127.0.0.1",
"last_sign_in_ip": "127.0.0.1"
}
Generate API Credentials¶
POST /api/users/{user_id}/api_credentials
Generate basic auth credentials for this user.
{
"api_credential": {
"name": "" # This will be visible in the user's profile.
}
}
Response
{
"api_credential": {
"id": 0,
"username": "",
"password": ""
}
}
Generate SSO Token¶
POST /api/users/{user_id}/user_sso
This can be used in conjunction with a custom registration process. After you create their user account, you can then request a SSO token and include that in the url: https://myportal.com/?username={email}&token={token}
.
You should perform this token and redirect all in a single request; the token will expire in less than 1 minute.
Response
{
"username": "j@j.local,
"token": "TOKEN",
"expires": "2021-03-01T23:36:57.214Z"
}
Suspend User¶
POST /api/users/{user_id}/suspension
This will stop all their containers and prevent them from using ComputeStacks.
Unsuspend User¶
DELETE /api/users/{user_id}/suspension