Difference between revisions of "Admin (Rest API)"
(Edited example JSON result for readability) |
m (→v2 - Coming Soon) |
||
Line 299: | Line 299: | ||
== v2 - Coming Soon == | == v2 - Coming Soon == | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=== Enable and Disable Two-Factor Authentication === | === Enable and Disable Two-Factor Authentication === |
Revision as of 15:57, 15 October 2015
Contents
v1 - Current
Index
URL:
[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins [GET] https://api.emailsrvr.com/v1/admins
Description:
This operation returns a list of admins under the account. If a customer account is specified, then a list of admins under that specific account will be returned.
Remarks:
To retrieve a list of admins owned by the account that is logged in, use "me" as the customer account number i.e. 'https://api.emailsrvr.com/v1/customers/me/domains'.
The index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: AdminList.xsd
Example:
get '/customers/999999/admins?size=5&page=1', 'text/xml'
XML Result Example:
<?xml version="1.0" encoding="utf-8"?> <adminList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:adminList"> <offset>0</offset> <size>50</size> <total>3</total> <admins> <admin> <adminId>apiadmin37</adminId> <type>super</type> <enabled>true</enabled> <locked>false</locked> </admin> <admin> <adminId>apiadmin76</adminId> <type>super</type> <enabled>true</enabled> <locked>false</locked> </admin> <admin> <adminId>apiadmin94</adminId> <type>super</type> <enabled>true</enabled> <locked>false</locked> </admin> </admins> </adminList>
Json Result Example:
{ "admins": [ { "adminId":"apiadmin37", "enabled":true, "locked":false, "type":"super" }, { "adminId":"apiadmin76", "enabled":true, "locked":false, "type":"super" }, { "adminId":"apiadmin94", "enabled":true, "locked":false, "type":"super" } ], "offset":0, "size":50, "total":3 }
Show
URL:
[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name) [GET] https://api.emailsrvr.com/v1/admins/(admin name)
Description:
The show operation will return detailed information about the specified admin.
Remarks:
The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: Admin.xsd
Example:
get '/customers/999999/admins/admin1', 'text/xml'
XML Result Example:
<?xml version="1.0" encoding="utf-8"?> <admin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:admin"> <adminId>apiadmin1</adminId> <type>super</type> <enabled>true</enabled> <locked>false</locked> <firstName>First</firstName> <lastName>Last</lastName> <email>first.last@rackspace.com</email> <passwordExpiration>10</passwordExpiration> <allowSimultaneousLogins>false</allowSimultaneousLogins> <restrictedIps> <restrictedIps>1.1.1.1</restrictedIps> <restrictedIps>1.1.1.2</restrictedIps> <restrictedIps>1.1.1.3</restrictedIps> </restrictedIps> </admin>
Json Result Example:
{ "adminId":"apiadmin1", "allowSimultaneousLogins":false, "email":"first.last@rackspace.com", "firstName":"First", "enabled":true, "locked":false, "lastName":"Last", "passwordExpiration":10, "restrictedIps":["1.1.1.1","1.1.1.2","1.1.1.3"], "type":"super" }
Add/Edit
URL:
Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name) [POST] https://api.emailsrvr.com/v1/admins/(admin name) Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name) [PUT] https://api.emailsrvr.com/v1/admins/(admin name)
Description:
Add a new admin or edit an existing admin under the specified account.
Field Name | Data Type | Description |
---|---|---|
type | string | Admin type (Required for Add). Must be "super", "standard" or "limited". Can't change permissions and domain access for limited admin at this point. |
password | string | Admin log in password (Required for Add) |
firstName | string | Admin first name (Required for Add) |
lastName | string | Admin last name (Required for Add) |
string | Admin contact email (Required for Add) | |
securityQuestion | string | Security question (Required for Add) |
securityAnswer | string | Security answer (Required for Add) |
passwordExpiration | int | The number of days in which password expires. 0 means password never expires. |
allowSimultaneousLogins | boolean | Allow simultaneous logins using this Administrative ID |
restrictedIps | string | Login restricted to IP address(es). Can be up to 3 valid addresses separated by commas. |
enabled | boolean | Enable/disable admin account |
locked | boolean | Lock/unlock admin account |
Example:
post '/customers/999999/admins/admin1', { 'type' => 'super', 'password' => 'password', 'firstName' => 'First', 'lastName' => 'Last', 'email' => 'first.last@rackspace.com', 'securityQuestion' => 'Q', 'securityAnswer' => 'A' }, 'text/xml'
put '/customers/999999/admins/admin2', { 'enabled' => 'true', 'locked' => 'false', 'passwordExpiration' => '0', 'allowSimultaneousLogins' => 'true', 'restrictedIps' => '1.1.1.1' }, 'text/xml'
Errors:
Description | HTTP Response Code | Sample Message |
---|---|---|
Password doesn't meet the requirements | 400 | Password must be 7 to 30 characters. |
Invalid email address | 400 | Invalid email address. |
Invalid restricted to IP address(es) | 400 | IP addresses must be valid addresses separated by commas. A maximum of 3 addresses may be entered. |
Delete
URL:
[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name) [DELETE] https://api.emailsrvr.com/v1/admins/(admin name)
Description:
Deletes the admin.
Example:
delete '/customers/999999/admins/admin1', 'text/xml'
v2 - Coming Soon
Enable and Disable Two-Factor Authentication
Enabling two-factor authentication requires installing [Google Authenticator] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.
You can set and remove keys for any admin on the account, including your own.
Generate a Secret Key
Description:
Generate a [TOTP] secret key for two-factor authentication.
Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.
URL:
[GET] /v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey Accept: application/json
HTTP response:
200 OK
with a JSON response:
{ "Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2" }
Example:
get '/v2/customers/me/admins/999999999/twoFactorAuth/newKey', 'application/json'
Enable Two-Factor Authentication
Description:
Provide a secret key and verification code to enable two-factor authentication for an admin.
URL:
[POST] /v2/customers/me/admins/(admin ID)/twoFactorAuth Content-type: application/json { "SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2", "VerificationCode": "123456" }
HTTP response:
204 No Content
Example:
post '/v2/customers/me/admins/999999999/twoFactorAuth', { "SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2", "VerificationCode": "123456" }, 'application/json'
Disable Two-Factor Authentication
Description:
Disable two-factor authentication for an admin.
URL:
POST /v2/customers/me/admins/reseller/twoFactorAuth Content-Type: application/json { "Enabled": false }
HTTP response:
204 No Content
Example:
post '/v2/customers/me/admins/999999999/twoFactorAuth', { "Enabled": false }, 'application/json'
Errors for GET requests
Description | HTTP Response Code | Sample Message |
---|---|---|
Invalid method | 404 Not Found | Make sure the URL is correct. (Did you include /newKey in the path?) |
Errors for POST requests
Description | HTTP Response Code | Sample Message |
---|---|---|
Invalid method (GET requests only) | 404 Not Found | Make sure the URL is correct. (Did you include /newKey in the path?)
|
POST body is empty | 400 Bad Request | Payload must be a valid JSON object. Make sure the POST body contains content. |
Wrong content type | 400 Bad Request | Payload must be a valid JSON object. Verify that the content type is application/json .
|
Missing fields | 400 Bad Request | Must send a "secretKey" property. Correctly populate empty fields in the POST body. |
Missing verification code | 400 Bad Request | Must send a "verificationCode" property. |
Secret key is invalid | 400 Bad Request | "secretKey" contains invalid characters. |
Secret key is null | 400 Bad Request | Must send a "secretKey" property. |
Verification code contains a leading zero | 400 Bad Request | The "verificationCode" value is not valid for the "secretKey" value. Enter a new verification code without a leading zero. |