Protocols/WebAPI/Auth/WebApp/getToken

WebAPI Protocol

Basic

Introduction

Clients

Whimsicals

Host Interaction

Flow

Authentication

• Client

• WebApp

Other Services

•

Foodgroups

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

Returns an NINA Authentication Token for an already authenticated user. The Authentication Token can be used to invoke Identity based NINA 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.nina.chat/auth/getToken
• 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 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.
  • 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
  • expiresIn -- Expiry time in secs
  • 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......"

            }
        }
    }}

Query String

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