Difference between revisions of "Admin (Rest API)"

Latest revision as of 06:14, 2 July 2019

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

Difference between revisions of "Admin (Rest API)"

Latest revision as of 06:14, 2 July 2019

Contents

v1 - Current

Index

Show

Add/Edit

Delete

v2 - Current

Enable and Disable Two-Factor Authentication

Generate a Secret Key

Enable Two-Factor Authentication

Disable Two-Factor Authentication

Errors for GET requests

Errors for POST requests

v3 - Current

List

Read

Create

Update

Delete

Navigation menu

Views

Personal tools

Navigation

Search

Tools