Protocols/WebAPI/Auth/Client/clientLogin

WebAPI Protocol

Basic

Introduction

Clients

Whimsicals

Host Interaction

Flow

Authentication

• Client

• WebApp

Other Services

•

Foodgroups

This page is about the clientLogin method for WebAPI Client authentication.

Initial Request

• URL
  • https://api.screenname.nina.bz/auth/clientLogin
  • NOTE: Supported on SSL (https) Only

• HTTP Method
  • POST (NOTE : All request parameters must passed in the POST body only, and not in the query string)

• HTTP Header
  • X-Forwarded-For (required if proxying clientLogin requests)
    • Clients/Servers using 'clientLogin' must pass the peer-ip from the requests they receive from their clients as X-Forwarded-For header in the 'clientLogin' request, so OpenAuth can enforce rate limits on the correct client IP. If the incoming request already has an X-Forwarded-For header, you should append peer-ip to it before sending it as X-Forwarded-For header in OpenAuth requests.

• Arguments
  • devId (required)
    • your developer Id required to access NINA APIs
  • f (required)
    • the required format of the response (XML, JSON, or the query string)
  • s (required)
    • the loginID of the source user
  • 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
  • pwd (optional)
    • User's Password when initiating the request for the first time or when Password challenge is returned in previous request
  • securid (optional)
    • User's SecurId when SecurId challenge is returned in previous request
  • asqAnswer (optional)
    • NINA Account Security Question's Answer when ASQ challenge is returned in previous request
  • word (optional)
    • Captcha Word when Captcha challenge is returned in previous request
  • context (optional)
    • Authentication Context returned in previous directLogin request when additional challenges are required
  • authMethod (optional)
    • Authentication Method required in addition to PWD (default)
    • Additional authMethod supported in this phase is "ASQ" (Account Security Question)
  • idType (optional)
    • You can pass value as "ICQ" to make sure you are authenticating an ICQ user (both numeric id and email alias)
    • No need to pass if you are just authenticating NINA/AIM users and even ICQ numeric ids only (not ICQ email aliases)
  • rlToken (optional)
    • Rate Limit Token obtained via a previous directLogin call with successful captcha challenge for the same user ('s' must match)
    • If user loginId doesn't match, rlToken would be ignored
  • clientName (optional)
    • An optional name of the Client
  • clientVersion (optional)
    • An optional version of the Client

Response Format

The following data elements would be returned in the response.

• token -- upon successful autentication
  • expiresIn -- Expiry time in secs
  • a - Authentication Token that can be used to invoke other services
• challenge -- when additional challenges are required to complete authentication
  • info (optional) -- ASQ Question in case of ASQ Challenge or Image url in case of Captcha challenge
  • context -- Authentication context to be returned on subsquent challenge responses
• rlToken -- Rate Limit token returned when user successful validates Captcha word and provides valid login credentials (loginId & password)
• sessionSecret -- Session Secret used to generate a Session Key used for signing subsequent NINA/AIM Open Services requests (WebAIM).
• hostTime -- OpenAuth Server current time in seconds since epoch format. Clients can use this to sync their clocks when making other NINA Open Service's calls with "ts" (timestamp) parameter.

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 name-value string in URL Query String format (name=value&name=value&...):

• statusCode
• statusText
• statusDetailCode
• requestId
• token_expiresIn
• token_a
• challenge_info
• challenge_context
• rlToken
• sessionSecret
• hostTime

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
• 460 - Missing required parameter
• 461 - Source required
• 462 - Parameter error
• 500 - Generic Server Error

Status DetailCodes (statusDetailCode)

• 3xxx - Authentication/Challenges Related errors
  • 3011 - Password-LoginId Required/Invalid
  • 3012 - SecurId Required/Invalid
  • 3013 - SecurId Next Token Required
  • 3014 - ASQ Required/Invalid
  • 3015 - Captcha Required/Invalid
  • 3016 - NINAKey Required
  • 3017 - Rights/Consent Required
  • 3018 - TOS/Privacy Policy Accept Required (this is not same as Rights/Consent - this is for future extension)
  • 3019 - Account Not allowed
  • 3020 - Email not confirmed
  • 3021 - Account needs to be updated (send user to NINA)

Sample Response

XML

     <response xmlns="https://api.login.nina.bz">
         <statusCode>200</statusCode>
         <statusText>OK</statusText>
         <data>
             <token>
                  <expiresIn>86400</expiresIn>
                  <a>%2FwEAAAAAZ%2F......</a>
             </token>
             <sessionSecret>AEqD4Tn4FwOwBMV7</sessionSecret> 
             <hostTime>1204563923</hostTime> 
         </data>
     </response>

JSON

         {"response":{
              "statusCode":200
              "statusText":"OK",
              "data":{
                   "sessionSecret":"GaPSXTfpvXILlNn6",
                   "hostTime":1204563933, 
                   "token":{
                       "expiresIn":86400,
                       "a":"%2FwEAAAAAEil22m......"
                   } 
              }
         }}

Query String

statusCode=200&statusText=OK&token_a=.....&token_expiresIn=86400&sessionSecret=....&hostTime=1204563933