Difference between revisions of "Admin (Rest API)"
(v1 documentation) |
(→v2 - Coming Soon) |
||
(18 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
__TOC__ | __TOC__ | ||
− | == | + | == v1 - Current == |
=== Index === | === Index === | ||
Line 8: | Line 8: | ||
''URL'': | ''URL'': | ||
− | <nowiki>[GET] https://api.emailsrvr.com/ | + | <nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki> |
− | <nowiki>[GET] https://api.emailsrvr.com/ | + | <nowiki>[GET] https://api.emailsrvr.com/v1/admins</nowiki> |
Line 19: | Line 19: | ||
''Remarks'': | ''Remarks'': | ||
− | To retrieve a list of admins owned by the account that is logged in, use "me" as the customer account number i.e. <nowiki>'https://api.emailsrvr.com/ | + | To retrieve a list of admins owned by the account that is logged in, use "me" as the customer account number i.e. <nowiki>'https://api.emailsrvr.com/v1/customers/me/domains'</nowiki>. |
− | The index operation only supports the GET HTTP verb. | + | The index operation only supports the GET HTTP verb. |
Line 27: | Line 27: | ||
<pre> | <pre> | ||
− | get '/customers/999999/admins?size=5&page=1 | + | get '/customers/999999/admins?size=5&page=1' |
</pre> | </pre> | ||
Line 42: | Line 42: | ||
<admin> | <admin> | ||
<adminId>apiadmin37</adminId> | <adminId>apiadmin37</adminId> | ||
+ | <firstName>John</firstName> | ||
+ | <lastName>Doe</lastName> | ||
<type>super</type> | <type>super</type> | ||
+ | <email>john.doe@example.com</email> | ||
<enabled>true</enabled> | <enabled>true</enabled> | ||
<locked>false</locked> | <locked>false</locked> | ||
+ | <twoFactorEnabled>true</twoFactorEnabled> | ||
</admin> | </admin> | ||
<admin> | <admin> | ||
<adminId>apiadmin76</adminId> | <adminId>apiadmin76</adminId> | ||
+ | <firstName>Jane</firstName> | ||
+ | <lastName>Doe</lastName> | ||
<type>super</type> | <type>super</type> | ||
+ | <email>jane.doe@example.com</email> | ||
<enabled>true</enabled> | <enabled>true</enabled> | ||
<locked>false</locked> | <locked>false</locked> | ||
+ | <twoFactorEnabled>true</twoFactorEnabled> | ||
</admin> | </admin> | ||
<admin> | <admin> | ||
<adminId>apiadmin94</adminId> | <adminId>apiadmin94</adminId> | ||
+ | <firstName>Test</firstName> | ||
+ | <lastName>User</lastName> | ||
<type>super</type> | <type>super</type> | ||
+ | <email>test.user@example.com</email> | ||
<enabled>true</enabled> | <enabled>true</enabled> | ||
<locked>false</locked> | <locked>false</locked> | ||
+ | <twoFactorEnabled>false</twoFactorEnabled> | ||
</admin> | </admin> | ||
</admins> | </admins> | ||
Line 66: | Line 78: | ||
<pre> | <pre> | ||
− | {"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} | + | { |
+ | "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 | ||
+ | } | ||
</pre> | </pre> | ||
Line 73: | Line 121: | ||
''URL'': | ''URL'': | ||
− | <nowiki>[GET] https://api.emailsrvr.com/ | + | <nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki> |
− | <nowiki>[GET] https://api.emailsrvr.com/ | + | <nowiki>[GET] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki> |
Line 84: | Line 132: | ||
''Remarks'': | ''Remarks'': | ||
− | The show operation only supports the GET HTTP verb. | + | The show operation only supports the GET HTTP verb. |
− | |||
''Example'': | ''Example'': | ||
<pre> | <pre> | ||
− | get '/customers/999999/admins/admin1 | + | get '/customers/999999/admins/admin1' |
</pre> | </pre> | ||
Line 125: | Line 172: | ||
''URL'': | ''URL'': | ||
<nowiki> | <nowiki> | ||
− | Add: [POST] https://api.emailsrvr.com/ | + | Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name) |
− | [POST] https://api.emailsrvr.com/ | + | [POST] https://api.emailsrvr.com/v1/admins/(admin name) |
− | Edit: [PUT] https://api.emailsrvr.com/ | + | Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name) |
− | [PUT] https://api.emailsrvr.com/ | + | [PUT] https://api.emailsrvr.com/v1/admins/(admin name) |
</nowiki> | </nowiki> | ||
Line 205: | Line 252: | ||
'securityQuestion' => 'Q', | 'securityQuestion' => 'Q', | ||
'securityAnswer' => 'A' | 'securityAnswer' => 'A' | ||
− | } | + | } |
− | |||
</pre> | </pre> | ||
Line 217: | Line 263: | ||
'allowSimultaneousLogins' => 'true', | 'allowSimultaneousLogins' => 'true', | ||
'restrictedIps' => '1.1.1.1' | 'restrictedIps' => '1.1.1.1' | ||
− | } | + | } |
− | |||
</pre> | </pre> | ||
Line 241: | 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 === | ||
Line 247: | Line 291: | ||
''URL'': | ''URL'': | ||
− | <nowiki>[DELETE] https://api.emailsrvr.com/ | + | <nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki> |
− | <nowiki>[DELETE] https://api.emailsrvr.com/ | + | <nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki> |
Line 259: | Line 303: | ||
<pre> | <pre> | ||
− | delete '/customers/999999/admins/admin1', ' | + | delete '/customers/999999/admins/admin1' |
+ | </pre> | ||
+ | |||
+ | == v2 - Current == | ||
+ | |||
+ | <!-- | ||
+ | # API paths for 2FAK | ||
+ | # Go-live date: late September 2015 | ||
+ | # URL: http://api-wiki.apps.rackspace.com/api-wiki/index.php/Admin_(Rest_API) | ||
+ | Changes by: Zach Corleissen | ||
+ | Date: 9/22/2015 | ||
+ | Project manager: Bob Black | ||
+ | --> | ||
+ | |||
+ | === Enable and Disable Two-Factor Authentication === | ||
+ | |||
+ | Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en 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 [[https://tools.ietf.org/html/rfc6238#page-4 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'': | ||
+ | |||
+ | <pre> | ||
+ | GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json' | ||
+ | </pre> | ||
+ | |||
+ | |||
+ | ''Response'': | ||
+ | |||
+ | <pre> | ||
+ | 200 OK | ||
+ | { | ||
+ | "Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2" | ||
+ | } | ||
+ | </pre> | ||
+ | |||
+ | |||
+ | ==== Enable Two-Factor Authentication ==== | ||
+ | |||
+ | |||
+ | ''Description'': | ||
+ | |||
+ | Provide a secret key and verification code to enable two-factor authentication for an admin. | ||
+ | |||
+ | |||
+ | ''Request'': | ||
+ | |||
+ | <pre> | ||
+ | POST /v2/customers/me/admins/(admin ID)/twoFactorAuth | ||
+ | { | ||
+ | "SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2", | ||
+ | "VerificationCode": "123456" | ||
+ | }, | ||
+ | 'application/json' | ||
+ | </pre> | ||
+ | |||
+ | |||
+ | ''Response'': | ||
+ | |||
+ | <code>204 No Content</code> | ||
+ | |||
+ | |||
+ | ==== Disable Two-Factor Authentication ==== | ||
+ | |||
+ | |||
+ | ''Description'': | ||
+ | |||
+ | Disable two-factor authentication for an admin. | ||
+ | |||
+ | |||
+ | ''Request'': | ||
+ | <pre> | ||
+ | POST /v2/customers/me/admins/reseller/twoFactorAuth | ||
+ | { | ||
+ | "Enabled": false | ||
+ | }, | ||
+ | 'application/json' | ||
+ | </pre> | ||
+ | |||
+ | ''Response'': | ||
+ | |||
+ | <code>204 No Content</code> | ||
+ | |||
+ | |||
+ | ''Example'': | ||
+ | |||
+ | <pre> | ||
+ | post /v2/customers/me/admins/999999999/twoFactorAuth | ||
+ | { | ||
+ | "Enabled": false | ||
+ | }, | ||
+ | 'application/json' | ||
</pre> | </pre> | ||
+ | |||
+ | |||
+ | ==== Errors for GET requests ==== | ||
+ | |||
+ | |||
+ | {| class="wikitable" | ||
+ | !''Description'' | ||
+ | !''HTTP Response Code'' | ||
+ | !''Sample Message'' | ||
+ | |- | ||
+ | | Invalid method | ||
+ | | 404 Not Found | ||
+ | | Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?) | ||
+ | |} | ||
+ | |||
+ | |||
+ | ==== Errors for POST requests ==== | ||
+ | |||
+ | |||
+ | {| class="wikitable" | ||
+ | !''Description'' | ||
+ | !''HTTP Response Code'' | ||
+ | !''Sample Message'' | ||
+ | |- | ||
+ | | Invalid method (GET requests only) | ||
+ | | 404 Not Found | ||
+ | | Make sure the URL is correct. (Did you include <code>/newKey</code> 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 <code>application/json</code>. | ||
+ | |- | ||
+ | | 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. | ||
+ | |} |
Revision as of 14:48, 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. |