View source for Admin (Rest API)

__TOC__

== v1 - Current ==

=== Index ===


''URL'':

 <nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
 <nowiki>[GET] https://api.emailsrvr.com/v1/admins</nowiki>


''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. <nowiki>'https://api.emailsrvr.com/v1/customers/me/domains'</nowiki>.

The index operation only supports the GET HTTP verb.


''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1'
</pre>


''XML Result Example'':

<pre>
<?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>
</pre>


''Json Result Example'':

<pre>
{
  "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>

=== Show ===

''URL'':

 <nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki>
 <nowiki>[GET] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>


''Description'':

The show operation will return detailed information about the specified admin.


''Remarks'':

The show operation only supports the GET HTTP verb.

''Example'':

<pre>
get '/customers/999999/admins/admin1'
</pre>

''XML Result Example'':

<pre>
<?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>
</pre>


''Json Result Example'':
<pre>
{"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"}
</pre>

=== Add/Edit ===

''URL'':
 <nowiki>
 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)
 </nowiki>


''Description'':

Add a new admin or edit an existing admin under the specified account.


{| class="wikitable"
!''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'':

<pre>
post '/customers/999999/admins/admin1',
     {
       'type' => 'super',
       'password' => 'password',
       'firstName' => 'First',
       'lastName' => 'Last',
       'email' => 'first.last@rackspace.com',
       'securityQuestion' => 'Q',
       'securityAnswer' => 'A'
     }
</pre>

<pre>
put '/customers/999999/admins/admin2',
     {
       'enabled' => 'true',
       'locked' => 'false',
       'passwordExpiration' => '0',
       'allowSimultaneousLogins' => 'true',
       'restrictedIps' => '1.1.1.1'
     }
</pre>


''Errors'':

{| class="wikitable"
!''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'':

 <nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki>
 <nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>


''Description'':

Deletes the admin.


''Example'':

<pre>
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>


==== 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.
|}

== v3 - Current ==

=== List ===
''URL'':

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

''Description'':

List administrators on an account.

''Query Params'':

{| class="wikitable"
!''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'':

<pre>
{
  "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
    }
  ]
}
</pre>

=== Read ===
''URL'':

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

''Description'':

Get a single administrator by their Id.

''JSON Response Example'':
<pre>
{
  "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?"
    }
  ]
}
</pre>

=== Create ===

''Description'':

Create a new administrator


''Request'':

<pre>
[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
}
</pre>

''Response'':
<pre>
200 OK
{
  "id": "admin12"
}
</pre>

=== Update ===

''Description'':

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

''Request'':

<pre>
[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
}
</pre>

''Response'':

<pre>
204 No Content
</pre>

=== Delete ===

''Description'':

Delete an administrator.

''Request'':

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

''Response'':

<pre>
204 No Content
</pre>