Difference between revisions of "Admin (Rest API)"

From Rackspace Email & Apps API
Jump to: navigation, search
(Added paths for two-factor authentication.)
Line 261: Line 261:
 
delete '/customers/999999/admins/admin1', 'text/xml'
 
delete '/customers/999999/admins/admin1', 'text/xml'
 
</pre>
 
</pre>
 +
 +
== v2 - Coming Soon ==
 +
 +
<!--
 +
# 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.
 +
 +
 +
''URL'':
 +
 +
<pre>
 +
[GET] /v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey
 +
Accept: application/json
 +
</pre>
 +
 +
 +
''HTTP response'':
 +
 +
<code>200 OK</code> with a JSON response:
 +
 +
<pre>
 +
{
 +
    "Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
 +
}
 +
</pre>
 +
 +
 +
''Example'':
 +
 +
<pre>
 +
get '/v2/customers/me/admins/999999999/twoFactorAuth/newKey', 'application/json'
 +
</pre>
 +
 +
 +
==== Enable Two-Factor Authentication ====
 +
 +
 +
''Description'':
 +
 +
Provide a secret key and verification code to enable two-factor authentication for an admin.
 +
 +
 +
''URL'':
 +
 +
<pre>
 +
[POST] /v2/customers/me/admins/(admin ID)/twoFactorAuth
 +
Content-type: application/json
 +
 +
{
 +
  "SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
 +
  "VerificationCode": "123456"
 +
}
 +
</pre>
 +
 +
 +
''HTTP response'':
 +
 +
<code>204 No Content</code>
 +
 +
 +
''Example'':
 +
 +
<pre>
 +
post '/v2/customers/me/admins/999999999/twoFactorAuth',
 +
    {
 +
        "SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
 +
        "VerificationCode": "123456"
 +
    },
 +
    'application/json'
 +
</pre>
 +
 +
 +
==== Disable Two-Factor Authentication ====
 +
 +
 +
''Description'':
 +
 +
Disable two-factor authentication for an admin.
 +
 +
 +
''URL'':
 +
<pre>
 +
POST /v2/customers/me/admins/reseller/twoFactorAuth
 +
Content-Type: application/json
 +
 +
{
 +
  "Enabled": false
 +
}
 +
</pre>
 +
 +
''HTTP response'':
 +
 +
<code>204 No Content</code>
 +
 +
 +
''Example'':
 +
 +
<pre>
 +
post '/v2/customers/me/admins/999999999/twoFactorAuth',
 +
    {
 +
        "Enabled": false
 +
    },
 +
    'application/json'
 +
</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 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.
 +
|}

Revision as of 15:14, 13 October 2015

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)
email 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.
Retrieved from "http://api-wiki.apps.rackspace.com/api-wiki/index.php?title=Admin_(Rest_API)&oldid=694"