Authentication

Overview

You will need to authenticate yourself before interacting with the AMEE API. There are two possible methods of authentication: HTTP Basic authentication, or authenticated sessions.

HTTP Basic

The simplest way to authenticate with AMEE is to provide your login details with each request, using the standard HTTP Basic login method. For example, using curl:

curl http://stage.amee.com/data -H "accept:application/xml" -u username:password

Because this method sends your login credentials with every request, you should probably only use this method over HTTPS connections to AMEE.

Also, because you must authenticate every time, API performance may be slower that the alternative authenticated session method, explained below.

Example HTTP Transaction

GET /data HTTP/1.1
Authorization: Basic AmfvcNB5OkYxMHRweTQtMzX=
accept:application/xml

HTTP/1.1 200 OK
...etc

Authenticated Sessions

To create an authenticated session, you need to request an authToken from the '/auth' API resource.

• URL:  http://{server}/auth
• Method: POST
• Request format: application/x-www-form-urlencoded
• Response format: application/xml, application/json
• Response code: 200 OK
• Response body: Details of the authenticated user, including API version.
• Extra data: "authToken" cookie and header, containing the authentication token that should be used for subsequent calls.

Parameters:

API Version	Parameter	Definition	Required
all	username	The user to authenticate as.	Yes
all	password	The password for the user.	Yes

Once you have an authToken, you can provide it instead of your full username and password in subsequent requests. You should supply the token in a cookie named "authToken" in each request.

Session Duration

The length of an authenticated session is limited. The maximum authenticated session duration is two hours. The maximum idle time for an authenticated session is thirty minutes. These durations are subject to change (for security reasons). It's important that your application logic can gracefully deal with an authentication failure on any API call and re-authenticate if needed. If the token expires, the API will return a status of 401 UNAUTHORIZED.

Example

Request

POST /auth HTTP/1.1
Accept: application/xml
Content-Type: application/x-www-form-urlencoded

username=my_username&password=my_password

Response

HTTP/1.1 200 OK
Set-Cookie: authToken=1KVARbypAjxLGViZ0Cg+UskZEHmqVkhx/PmEvzkPGpnUlH17KQbJ58xfapXiewVVPvG2CtrQNTuawY+KWU4Dxx08570dM2Z0sZAoeijdlucuCOvAyHhi9A==; 
authToken: 1KVARbypAjxLGViZ0Cg+UskZEHmqVkhx/PmEvzkPGpnUlH17KQbJ58xfapXiewVVPvG2CtrQNTuawY+KWU4Dxx08570dM2Z0sZAoeijdlucuCOvAyHhi9A==
Content-Type: application/xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
  <Resources>
    <SignInResource>
      <Next>http://stage.amee.com/auth</Next>
      <User uid="1A6307E2B531">
      <Status>ACTIVE</Status>
      <Type>STANDARD</Type>
      <GroupNames>
        <GroupName>amee</GroupName>
        <GroupName>Standard</GroupName>
        <GroupName>All</GroupName>
      </GroupNames>
      <ApiVersion>1.0</ApiVersion>
    </User>
  </SignInResource>
</Resources>

Using the authToken in API requests

The authToken should be provided in a cookie named "authToken" for subsequent requests.

GET /data HTTP/1.1
Cookie: authToken=1KVARbypAjxLGViZ0Cg+UskZEHmqVkhx/PmEvzkPGpnUlH17KQbJ58xfapXiewVVPvG2CtrQNTuawY+KWU4Dxx08570dM2Z0sZAoeijdlucuCOvAyHhi9A==
accept:application/xml

HTTP/1.1 200 OK
...etc