Admin (Rest API)

2019-07-02T14:14:54Z

Paul.trampert:

__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 ==



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

Rackspace Email & Apps API - User contributions [en]

Admin (Rest API)