Difference between revisions of "Admin (Rest API)"
(→Index) |
(→Add/Edit) |
||
Line 286: | Line 286: | ||
| IP addresses must be valid addresses separated by commas. A maximum of 3 addresses may be entered. | | IP addresses must be valid addresses separated by commas. A maximum of 3 addresses may be entered. | ||
|} | |} | ||
− | |||
=== Delete === | === Delete === |
Revision as of 14:41, 20 August 2018
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.
Example:
get '/customers/999999/admins?size=5&page=1'
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> <firstName>John</firstName> <lastName>Doe</lastName> <type>super</type> <email>john.doe@example.com</email> <enabled>true</enabled> <locked>false</locked> <twoFactorEnabled>true</twoFactorEnabled> </admin> <admin> <adminId>apiadmin76</adminId> <firstName>Jane</firstName> <lastName>Doe</lastName> <type>super</type> <email>jane.doe@example.com</email> <enabled>true</enabled> <locked>false</locked> <twoFactorEnabled>true</twoFactorEnabled> </admin> <admin> <adminId>apiadmin94</adminId> <firstName>Test</firstName> <lastName>User</lastName> <type>super</type> <email>test.user@example.com</email> <enabled>true</enabled> <locked>false</locked> <twoFactorEnabled>false</twoFactorEnabled> </admin> </admins> </adminList>
Json Result Example:
{ "admins":[ { "adminId":"apiadmin37", "firstName": "John", "lastName": "Doe", "enabled":true, "locked":false, "type":"super", "email":"john.doe@example.com", "twoFactorEnabled":true }, { "adminId":"apiadmin76", "firstName": "Jane", "lastName": "Doe", "enabled":true, "locked":false, "type":"super", "email":"jane.doe@example.com", "twoFactorEnabled":true }, { "adminId":"apiadmin94", "firstName": "Test", "lastName": "User", "enabled":true, "locked":false, "type":"super", "email":"test.user@example.com", "twoFactorEnabled":false } ], "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.
Example:
get '/customers/999999/admins/admin1'
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' }
put '/customers/999999/admins/admin2', { 'enabled' => 'true', 'locked' => 'false', 'passwordExpiration' => '0', 'allowSimultaneousLogins' => 'true', 'restrictedIps' => '1.1.1.1' }
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'
v2 - Current
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.
Request:
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
Response:
200 OK { "Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2" }
Enable Two-Factor Authentication
Description:
Provide a secret key and verification code to enable two-factor authentication for an admin.
Request:
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth { "SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2", "VerificationCode": "123456" }, 'application/json'
Response:
204 No Content
Disable Two-Factor Authentication
Description:
Disable two-factor authentication for an admin.
Request:
POST /v2/customers/me/admins/reseller/twoFactorAuth { "Enabled": false }, 'application/json'
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 is an int | 400 Bad Request | Must send "verificationCode" as a string in quotes. |