Admin (Rest API)

From Rackspace Email & Apps API
Jump to: navigation, search

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.

v3 - Current

List

URL: 

[GET] https://api.emailsrvr.com/v3/customers/(customer account number)/admins
[GET] https://api.emailsrvr.com/v3/admins

Description:

List administrators on an account.

Query Params:

Param Name Data Type Description
contains string filter list to match on user name, first name, last name, or email address
start int Paging parameter indicating the starting record. (Default: 0)
pageSize int The number of records from the overall result set that should be returned (Default: 10)
sortDirection string Direction to sort. (Default: 'asc')
sortProperty string Sort list by this property. Valid values are active, name (first + last), adminType, and primary. (Default: name)
username string Search specifically by username
primaryContact boolean Return only the primary contacts
notificationType string list Filter by the comma delimited list of notification types to include. Valid items: alerts, billing, updates

JSON Response Example: 

{
  "start": 0,
  "pageSize": 50,
  "sortDirection": "desc",
  "sortProperty": "username",
  "total": 2,
  "contains": "",
  "adminLimit": 20,
  "results": [
    {
      "id": "a0910b79-b14d-4240-a5f5-2dc47e9a4beb",
      "firstName": "Jane",
      "lastName": "Doe",
      "userName": "jane.doe",
      "adminType": "Standard",
      "emailAddress": "jane.doe@example.com",
      "phoneNumber": "555-555-1234",
      "lastLogin": "2018-08-22T13:34:55.000Z",
      "securityQuestions": [
        {
          "question": "Question 1?"
        },
        {
          "question": "Question 2?"
        }
      ],
      "isActive": true,
      "primaryContact": true
    },
    {
      "id": "cc073092-9ee9-4771-9e16-6ffcf11c0c73",
      "firstName": "Ralph",
      "lastName": "Doe",
      "userName": "ralph.doe",
      "adminType": "Standard",
      "emailAddress": "jane.doe@example.com",
      "phoneNumber": "555-555-1234",
      "lastLogin": "2018-08-22T07:34:55.000Z",
      "securityQuestions": [],
      "isActive": false,
      "primaryContact": true
    }
  ]
}

Read

URL: 

[GET] https://api.emailsrvr.com/v3/customers/(customer account number)/admins/(adminId)
[GET] https://api.emailsrvr.com/v3/admins/(adminId)

Description:

Get a single administrator by their Id.

JSON Response Example: 

{
  "id": "a0910b79-b14d-4240-a5f5-2dc47e9a4beb",
  "firstName": "Jane",
  "lastName": "Doe",
  "userName": "jane.doe",
  "adminType": "Standard",
  "emailAddress": "jane.doe@example.com",
  "phoneNumber": "555-555-1234",
  "isActive": true,
  "isLocked": false,
  "lastLogin": "2018-09-11T13:11:41.000Z",
  "lastVerified": "2018-09-11T13:11:41.000Z",
  "title": "",
  "ipAllowed": [
    "192.168.14.22"
  ],
  "numFailedLogin": 1,
  "multifactorRequired": false,
  "passwordExpirationInDays": 30,
  "passwordLastModified": "2018-09-11T13:11:41.000Z",
  "primaryContact": true,
  "alerts": true,
  "billing": true,
  "updates": true,
  "securityQuestions": [
    {
      "question": "Question 1?"
    },
    {
      "question": "Question 2?"
    }
  ]
}

Create

Description:

Create a new administrator


Request: 

[POST] https://api.emailsrvr.com/v3/customers/(customer account number)/admins
{
  "accountNumber": "12345",
  "firstName": "Jane",
  "lastName": "Doe",
  "userName": "jane.doe",
  "adminType": "Standard",
  "emailAddress": "jane.doe@example.com",
  "phoneNumber": "555-555-1234",
  "securityQuestion": "",
  "securityAnswer": "",
  "multifactorRequired": true,
  "ipAllowed": [
    "192.168.34.2"
  ],
  "authorizationClaims": [
    {
      "category": "email-hosting",
      "claim": "aliases"
    },
    {
      "category": "domain",
      "claim": "braineaters.org"
    }
  ],
  "password": "Asdfasdf1",
  "primaryContact": true,
  "alerts": true,
  "billing": true,
  "updates": true
}

Response: 

200 OK
{
  "id": "admin12"
}

Update

Description:

Update an administrator. Fields not included will not be updated.

Request: 

[PUT] https://api.emailsrvr.com/v3/customers/(customer account number)/admins/(administrator id)
{
  "firstName": "Jane",
  "lastName": "Doe",
  "adminType": "Standard",
  "emailAddress": "jane.doe@example.com",
  "phoneNumber": "555-555-1234",
  "securityQuestion": "",
  "securityAnswer": "",
  "isActive": true,
  "lastVerified": "2015-01-01T22:23:54.000Z",
  "ipAllowed": [
    "127.0.0.1"
  ],
  "passwordExpirationInDays": 30,
  "primaryContact": true,
  "alerts": true,
  "billing": true,
  "updates": true,
  "authorizationClaims": {
    "allow": [
      {
        "category": "email-hosting",
        "claim": "aliases"
      },
      {
        "category": "domain",
        "claim": "braineaters.org"
      }
    ],
    "deny": []
  },
  "deleteContactQuestion": true
}

Response: 

204 No Content

Delete

Description:

Delete an administrator.

Request: 

[DELETE] https://api.emailsrvr.com/v3/customers/(customer account number)/admins/(administrator id)

Response: 

204 No Content
Retrieved from "http://api-wiki.apps.rackspace.com/api-wiki/index.php?title=Admin_(Rest_API)&oldid=770"