Difference between revisions of "Admin (Rest API)"

From Rackspace Email & Apps API
Jump to: navigation, search
(→‎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 13:41, 20 August 2018

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)
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'
     }

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