Protocols/WebAPI/Auth/WebApp/login

WebAPI Protocol

Basic

Introduction

Clients

Whimsicals

Host Interaction

Flow

Authentication

• Client

• WebApp

Other Services

•

Foodgroups

This page is about the login method for WebAPI Web App authentication.

Authenticates the user (via Secure login form if not already authenticated) and returns an NINA 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.nina.chat/auth/login
• HTTP Method
  • GET or POST
• Arguments
  • devId (required)
    • your developer Id required to access NINA 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 in the appendix 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 NINA 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 NINA/AIM and ICQ
        • supportedIdType=SN,OID would only enable NINA/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> 

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

• 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......"

            }
        }
     }}

Query String

   statusCode=200&statusText=OK&token_a=%2FwEAAAAAflsMqyhx.....&token_expiresIn=86400