Protocols/WebAPI/Auth/WebApp/getInfo

From NINA Wiki
Revision as of 15:38, 30 April 2025 by Animadoria (talk | contribs) (Created page with "{{Protocols/WebAPI}} This page is about the getInfo method for WebAPI Web App authentication. 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...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
WebAPI Protocol
Basic
Introduction
Clients
Whimsicals
Host Interaction
Flow
Authentication
• Client
• WebApp
Other Services
•
Foodgroups

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

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 NINA 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.nina.chat/auth/getInfo
  • 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.
    • 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.ilovenina.com
          • Protocol (ex. http:// or https://) and Port (ex. :8000) are ignored
        • Path until the last '/' must match if there are multiple sub-directories in the path - Ex. /login/ if url is http://www.ilovenina.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.ilovenina.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
            }
         }
    }}

Query String

    statusCode=200&statusText=OK&userData_loginId=ChattingChuck
     &userData_displayName=Chuck&userData_lastAuth=1161932570000
Retrieved from "https://wiki.nina.chat/index.php?title=Protocols/WebAPI/Auth/WebApp/getInfo&oldid=8771"