Home ›

Authentication for Web Sites and Browser based Web-Apps

The AOL Open Authentication API (OpenAuth) empowers third-party web sites and applications to authenticate AOL and AIM users through their Web Sites/Applications. An AIM/AOL/ICQ user can now log into a third-party Web Site/Application and seamlessly access AOL Open web services or new services built on top of AOL services. Using the AOL Open Authentication API, external Web Sites/Applications can call AOL's Secure Login Page and get an Authentication Token. Upon user's permission via AOL's Secure Consent Page, they can even use the Authentication Token to access AOL/AIM Open Web Services on behalf of the user.

In the typical usage illustrated below, the AIM/AOL member successfully accesses his/her Buddy List directly through the external site once all the appropriate handshakes and validations have occurred between the user, the external site, OpenAuth API, and AOL's backend. In other words, now third-party implementations can securely offer cool new applications and services to a vastly expanded base of users.

Note: Steps 6 - 10 only occur once per session or once per user based on user's permission choice (Grant once or always).

Enabling Authentication on a Web Site using AOL OpenAuth API involves implementing the following easy steps:

  1. Redirecting the user to OpenAuth "login" url with appropriate required parameters
  2. Handling the response redirect from OpenAuth "login" to receive Authentication token and process error codes as required
  3. Making AOL Open Service requests along with the Authentication token obtained from "login"
    • Optionally, using OpenAuth "getInfo" method to validate token and retrieve user's information.

Enabling Authentication for a browser based App (Web 2.0/AJAX Model) involves implementing the following easy steps:

  1. Sending an Asynchronous call to OpenAuth's "getToken" method to retrieve Authentication token if a user is already signed in. The "getToken" request can be made as a JSONP call from the browser side.
  2. If the user is not already logged in, redirect the user to OpenAuth "login" page in one of the three following ways:
    1. Redirect to OpenAuth "login" url with required parameters
    2. Redirect to OpenAuth "login" url with required parameters in an IFRAME with no "succUrl" parameter (please refer to appendix for a list of URL Fragments used to notify Authentication status)
    3. Redirect to OpenAuth "login" url with required parameters in a new browser window
  3. Handling the response from OpenAuth getToken/login methods to receive Authentication token and process error codes as required
  4. Making AOL Open Service requests along with the Authentication token obtained from "login"
    • Optionally, using OpenAuth "getInfo" method to validate token and retrieve user's information.

API Reference:

login

Authenticates the user (via Secure login form if not already authenticated) and returns an AOL Authentication Token in a browser. The "login" method is only supported as a browser redirect api. Typically a web application constructs a login Url using this method along with the required parameters listed below. This method depends on Secure Authentication Cookies set in the browser, so it cannot be invoked from Server

  • URL
    • http(s)://api.screenname.aol.com/auth/login
  • HTTP Method
    • GET or POST
  • Arguments
    • devId (required)
      • your developer Id required to access AOL APIs
    • f (required)
      • the required format of the response (json or xml or qs)
    • succUrl (optional)
      • the destination url where the site wants the user to be redirected to upon successful authentication or when user cancels login process. If no succUrl is provided, it would be assumed that the calling site is using IFRAMEs to load the login page. In which case, URL Fragments documented below would be used notify about user flow status that Web Sites/Applications can use to detect the state and close the IFRAME accordingly
      • NOTE: The succUrl is used as the "Trust Url" that's displayed to the users and also used to limit the scope of the Authentication Token.
      • If no succUrl is used, the REFERER header will be used as the "Trust Url".
      • If neither succUrl nor REFERER header are available, then the request would be blocked.
    • s (optional)
      • the loginID of the source user (if known)
    • language (optional)
      • the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us". Check below for our current supported language list.
      • tokenType (optional)
      • "shortterm" (session based token - max life 24 hrs - default) or "longterm" (valid for 1 year) or any non-negative long value representing the required Token validity in seconds
    • c (optional)
      • the callback method to use when using jsonp convention (argument f = json)
    • r (optional)
      • an URL safe string to be used as requestId - when passed it is returned back in the response
    • uiType (optional)
      • 'mini' - if a smaller version (230x230px) of OpenAuth login page is required.
      • The 'mini' Login Page is also iPhone compatible.
    • supportedIdType (optional)
      • comma separated list of allowed Identity Types
      • current supported list includes:
        • SN -- includes all AOL and AIM Users
        • ICQ -- includes all ICQ users
        • OID -- includes OpenID Users
        • Ex.
          • supportedIdType=SN,ICQ,OID would enable all
          • supportedIdType=SN,ICQ would only enable AOL/AIM and ICQ
          • supportedIdType=SN,OID would only enable AOL/AIM and OpenID
  • Response Format

The following data elements would be returned in the response as specified in the XML/JSON/QS formats defined below:

  • token
    • expiresIn -- Expiry time in secs
    • a - Authentication Token that can be used to invoke other services

If the requested response format is xml or json and 'succUrl' parameter is provided in the request, the response data will be url encoded and appended to the 'succUrl' as a Query Parameter "res". ex. ${succUrl}?res=<response-data>.

  • The XML standard wrapper: 
 <response>
<statusCode />
<statusText />
<statusDetailCode />
<requestId />
<data>
....
</data>
</response>
  • JSON 
 {"response":{
"statusCode":""
"statusText":"",
"statusDetailCode":""
"requestId":""
"data":{
....
} }}
  • Query String

The following parameters will be returned back as URL query parameters to your succUrl 

 statusCode
statusText
statusDetailCode
requestId
token_expiresIn
token_a
  • Error Codes
    • 200 - Success (Ok)
    • 400 - Invalid request
    • 401 - Unauthorized (authentication required)
    • 405 - Method not allowed
    • 408 - Request timeout
    • 430 - Source rate limit reached
    • 440 - Invalid Key
    • 441 - Key usage limit reached
    • 442 - Key invalid IP
    • 443 - Key used from unauthorized site
    • 460 - Missing required parameter
    • 461 - Source required
    • 462 - Parameter error
    • 500 - Generic Server Error
  • Sample Response
    • XML 
 <response xmlns="https://api.login.aol.com">
<statusCode>200</statusCode>
<statusText>OK</statusText>
<data>
<token>
<expiresIn>86400</expiresIn>
<a>%2FwEAAAAAZ%2F......</a>
</token>
</data>
</response>
  • json 
 {"response":{
"statusCode":200
"statusText":"OK",
"data":{
"token":{
"expiresIn":86400,
"a":"%2FwEAAAAAEil22m......"
}
}
}}
  • qs 
 statusCode=200&statusText=OK&token_a=%2FwEAAAAAflsMqyhx.....&token_expiresIn=86400

getToken

Returns an AOL Authentication Token for an already authenticated user. The Authentication Token can be used to invoke Identity based AOL Services on behalf of the user or can be used to check user's Authentication status. This method can be invoked either as a redirect or as a JSON/JSONP call from the browser but cannot be invoked from Server Side as it depends on Secure Authentication Cookies set in the user's browser.

If the user is not already authenticated, a response with statusCode '401' (Authentication Required) along with a login redirectURL is returned.

  • URL
    • http(s)://api.screenname.aol.com/auth/getToken
  • HTTP Method
    • GET or POST
  • Arguments
    • devId (required)
      • your developer Id required to access AOL APIs
    • f (required)
      • the required format of the response (json or xml or qs)
    • succUrl (optional)
      • the destination url where the site wants the user to be redirected to upon success or failure. If no succUrl is provided, it would be assumed that the calling site is using JSON/JSONPcall and the response is simply returned as a JSON object.
      • NOTE: The succUrl is used as the "Trust Url" that's displayed to the users and also used to limit the scope of the Authentication Token.
      • If no succUrl is used, the REFERER header will be used as the "Trust Url".
      • If neither succUrl nor REFERER header are available, then the request would be blocked.
    • s (optional)
      • the loginID of the source user (if known)
    • language (optional)
      • the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2letter language code for I18N (default: en) and the locale is the 2letter Locale code for I18N (default: us). If not passed in, thelanguage will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us". Check below for our current supported language list.
    • tokenType (optional)
      • "shortterm" (session based token - max life 24 hrs - default) or "longterm" (valid for 1 year) or any non-negative long value representing the required Token validity in seconds
    • c (optional)
      • the callback method to use when using jsonp convention (argument f = json)
    • r (optional)
      • an URL safe string to be used as requestId - when passed it is returned back in the response
  • Response Format

The following data elements would be returned in the response 

 * token
o expiresIn -- Expiry time in secs
o a - Authentication Token that can be used to invoke other services
* redirectURL -- Redirect URL where the user should be redirected to.

If the requested response format is xml or json and 'succUrl' parameter is provided in the request, the response data will be url encoded and appended to the 'succUrl' as a Query Parameter "res". ex. ${succUrl}?res=<response-data>.

  • The XML standard wrapper: 
 <response>
<statusCode />
<statusText />
<statusDetailCode />
<requestId />
<data>
....
</data>
</response>
  • The JSON standard wrapper 
 {"response":{
"statusCode":""
"statusText":"",
"statusDetailCode":""
"requestId":""
"data":{
....
} }}
  • Query String

The following parameters will be returned back as URL query parameters to your succUrl 

 statusCode
statusText
statusDetailCode
requestId
token_expiresIn
token_a
redirectURL
  • Error Codes
    • 200 - Success (Ok)
    • 330 - More authentication required
    • 400 - Invalid request
    • 401 - Unauthorized (authentication required)
    • 405 - Method not allowed
    • 408 - Request timeout
    • 430 - Source rate limit reached
    • 440 - Invalid Key
    • 441 - Key usage limit reached
    • 442 - Key invalid IP
    • 443 - Key used from unauthorized site
    • 444 - token used from unauthorized site (Referer doesn't match the value in token)
    • 460 - Missing required parameter
    • 462 - Parameter error
    • 500 - Generic Server Error
  • Sample Response
    • XML 
 <response xmlns="https://api.login.aol.com">
<statusCode>200</statusCode>
<statusText>OK</statusText>
<data>
<token>
<expiresIn>86400</expiresIn>
<a>%2FwEAAAAAZ%2F......</a>
</token>
</data>
</response>
  • json 
 {"response":{
"statusCode":200,
"statusText":"OK",
"data":{
"token":{
"expiresIn":86400,
"a":"%2FwEAAAAAZ%2F......"
}
}
}}
  • qs 
 statusCode=200&statusText=OK&token_a=%2FwEAAAAAflsMqyhx.....&token_expiresIn=86400

getInfo

Validates the Authentication Token issued and returns user's loginId and displayName along with last authentication time stamp. The getInfo method can be invoked in a browser either as a redirect or as a JSON/JSONP call from the browser.

This method can also be invoked from Server Side, in which case the "referer" header passed in by the browser to your server must be passed as the "referer" argument.

When the given Authentication Token is expired or corrupted or invalid or used for unauthorized site (referer), a login redirectURL would be returned in the response.

If the given Authentication Token doesn't have enough permission to allow access to AOL Services on behalf of the user, a consent redirectURL would be returned in the response. The user should be redirected to the consent url to request for user's permission by passing along the same api arguments that are used to invoke this method.

  • URL
    • http(s)://api.screenname.aol.com/auth/getInfo
  • HTTP Method
    • GET or POST
  • Arguments
    • devId (required)
      • your developer Id required to access AOL APIs
    • f (required)
      • the required format of the response (json or xml or qs)
    • succUrl (optional)
      • the destination url where the site wants the user to be redirected to upon success or failure. If no succUrl is provided, it would be assumed that the calling site is using JSON/JSONPcall and the response is simply returned as a JSON object.
      • NOTE: The succUrl is used as the "Trust Url" that's displayed to the users and also used to limit the scope of the Authentication Token.
      • If no succUrl is used, the REFERER header will be used as the "Trust Url".
      • If neither succUrl nor REFERER header are available, then the request would be blocked.
    • s (optional)
      • the loginID of the source user (if known)
    • language (optional)
      • the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us". Check below for our current supported language list.
    • referer (optional)
      • the referer header value - when invoked from server side, the calling app must pass the HTTP Referer header passed by the browser.
      • IMP: The referer must match the 'succUrl' (or 'HTTP Referer' when 'succUrl' is not used) used to obtain Authentication token using 'getToken' or 'login' method as below:
        • FQDN (Fully Qualified Domain Name) must match - Ex. www.uncutvideo.com, www.iloveaol.com
        • Path until the last '/' must match if there are multiple sub-directories in the path - Ex. /login/ if url is http://www.iloveaol.com/login/login.html
        • File name until the '?' must match if there are no sub-directories in the path - Ex. /index.html if url is http://www.iloveaol.com/login.html
    • reqAuthFreshness (optional)
      • required Authentication freshness in secs ( since the user was last authenticated). Default is 24 hrs (86400 secs)
    • c (optional)
      • the callback method to use when using jsonp convention (argument f = json)
    • r (optional)
      • an URL safe string to be used as requestId - when passed it is returned back in the response
    • a (required)
      • the Authentication token returned by login or getToken methods
  • Response Format

The following data elements would be returned in the response

  • userData
    • loginId -- User's Login Identifier
    • displayName -- User's Display Name
    • lastAuth -- Seconds since the user was last authenticated
  • redirectURL -- Redirect URL where the user should be redirected to.

If the requested response format is xml or json and 'succUrl' parameter is provided in the request, the response data will be url encoded and appended to the 'succUrl' as a Query Parameter "res". ex. ${succUrl}?res=<response-data>.

  • The XML standard wrapper: 
 <response>
<statusCode />
<statusText />
<statusDetailCode />
<requestId />
<data>
....
</data>
</response>
  • The JSON standard wrapper 
 {"response":{
"statusCode":""
"statusText":"",
"statusDetailCode":""
"requestId":""
"data":{
....
} }}
  • Query String

The following parameters will be returned back as URL query parameters to your succUrl 

 statusCode
statusText
statusDetailCode
requestId
userData_loginId
userData_displayName
userData_lastAuth
redirectURL
  • Error Codes
    • 200 - Success (Ok)
    • 330 - More authentication required
    • 340 - More rights required
    • 400 - Invalid request
    • 401 - Unauthorized (authentication required)
    • 405 - Method not allowed
    • 408 - Request timeout
    • 430 - Source rate limit reached
    • 440 - Invalid Key
    • 441 - Key usage limit reached
    • 442 - Key invalid IP
    • 443 - Key used from unauthorized site
    • 444 - token used from unauthorized site (Referer doesn't match the value in token)
    • 450 - Rights denied
    • 451 - Permission denied
    • 460 - Missing required parameter
    • 462 - Parameter error
    • 500 - Generic Server Error
  • Sample Response
    • XML 
 <response xmlns="https://api.login.aol.com">
<statusCode>200</statusCode>
<statusText>OK</statusText>
<data>
<userData>
<loginId>ChattingChuck</loginId>
<displayName>Chuck</displayName>
<lastAuth>1161932570000</lastAuth>
</userData>
</data>
</response>
  • json 
 {"response":{
"statusCode":200,
"statusText":"OK",
"data":{
"userData":{
"loginId":"ChattingChuck",
"displayName":"Chuck",
"lastAuth":1161932570000
}
}
}}
  • qs 
 statusCode=200&statusText=OK&userData_loginId=ChattingChuck
&userData_displayName=Chuck&userData_lastAuth=1161932570000

logout

Terminates the user's authentication session and invalidates the Authentication Tokens assigned to all Web Sites/Applications for the current user. The logout method can be invoked either as a redirect with succUrl argument or as a JSON/JSONP call in a browser and also can be invoked from Server

  • URL
    • http(s)://api.screenname.aol.com/auth/logout
  • HTTP Method
    • o GET or POST
  • Arguments
    • devId (required)
      • your developer Id required to access AOL APIs
    • f (required)
      • the required format of the response (json or xml or qs)
    • succUrl (optional)
      • the destination url where the site wants the user to be redirected to upon successful logout. If no succUrl is provided, it would be assumed that the calling site is using JSON/JSONPcall and the response is simply returned as a JSON object.
      • NOTE: The succUrl is used as the "Trust Url" that's displayed to the users and also used to limit the scope of the Authentication Token.
      • If no succUrl is used, the REFERER header will be used as the "Trust Url".
      • If neither succUrl nor REFERER header are available, then the request would be blocked.
    • s (optional)
      • the loginID of the source user (if known)
    • language (optional)
      • the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us". Check below for our current supported language list.
    • c (optional)
      • the callback method to use when using jsonp convention (argument f = json)
    • r (optional)
      • an URL safe string to be used as requestId - when passed it is returned back in the response
    • a (required)
      • the Authentication token returned by login or getToken methods
  • Response Format

Response would contain the statusCode indicating whether the logout was successful or not.

If the requested response format is xml or json and 'succUrl' parameter is provided in the request, the response data will be url encoded and appended to the 'succUrl' as a Query Parameter "res". ex. ${succUrl}?res=<response-data>.

  • The XML standard wrapper: 
 <response>
<statusCode />
<statusText />
<statusDetailCode />
<requestId />
</response>
  • The JSON standard wrapper 
 {"response":{
"statusCode":""
"statusText":"",
"statusDetailCode":""
"requestId":""
}}
  • Query String 
 The following parameters will be returned back as URL query parameters to your succUrl
 statusCode
statusText
statusDetailCode
requestId
  • Error Codes
    • 200 - Success (Ok)
    • 304 - Not modified
    • 400 - Invalid request
    • 405 - Method not allowed
    • 408 - Request timeout
    • 430 - Source rate limit reached
    • 440 - Invalid Key
    • 441 - Key usage limit reached
    • 442 - Key invalid IP
    • 443 - Key used from unauthorized site
    • 444 - token used from unauthorized site (Referer doesn't match the value in token)
    • 460 - Missing required parameter
    • 461 - Source required
    • 462 - Parameter error
    • 500 - Generic Server Error
  • Sample Response
    • XML 
 <response xmlns="https://api.login.aol.com">
<statusCode>200</statusCode>
<statusText>OK</statusText>
</response>
  • json 
 {"response":{
"statusCode":200,
"statusText":"OK"
}}
  • qs 
 statusCode=200&statusText=OK

Appendix

When "login" and "consent" (returned when a Site tries to access AOL Services on behalf of the user) urls are invoked in IFRAMEs (without "succUrl" param) instead of the standard full browser redirects (with "succUrl" param), the following values are set as URL Fragments to notify the Web Site/Application about the user's flow status: 

1. AUTHCANCEL - user canceled login flow (user clicked on cancel button)
2. AUTHDONE - user successfully authenticated
3. INVALIDCALLBACK - invalid jsonp callback ('c' param) value
4. CONSENTINVALIDTOKEN - consent url called with invalid token (expired/corrupted/replayed/invalid usage)
5. CONSENTDONE - consent process done (user clicked on Allow Always or Allow this time only buttons)
6. CONSENTCANCEL - user denied permission
» Submitted by Developer Network on March 5, 2008 - 3:31am.