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 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 (json or xml or qs)
  • 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.