Protocols/WebAPI/Auth/Client/getConsent

From NINA Wiki
Revision as of 22:54, 25 March 2020 by AD (talk | contribs) (AD moved page Protocols/WebAPI/Auth/getConsent to Protocols/WebAPI/Auth/Client/getConsent without leaving a redirect)
(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 getConsent method for WebAPI Client authentication.

This method should only be used to obtain the user's consent (permission) to access an NINA/AIM Service on behalf of the user, when instructed to by the NINA/AIM Services with status code '340' along with a redirect URL.

For client logins (token obtained via 'clientLogin' methods), the client must do a "direct" request to the getConsent Url along with the required parameters as specified below. The getConsent Url returned by the NINA/AIM Services contains only the "enc" parameter, so you must add the other required parameters specified below.

Initial Request

  • URL
    • http(s)://api.screenname.nina.bz/auth/getConsent
  • HTTP Method
    • GET or POST
  • 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)
    • enc (required)
      • The encrypted token returned by the previous call to OpenAuth or NINA/AIM Open Service as part of the 'redirectUrl'. Since the getConsent url already contains the 'enc' parameter, you don't need to manually add it.
    • 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.
    • 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
    • context (optional)
      • Context returned in previous getConsent request when additional challenges are required
    • word (optional)
      • Captcha Word when Captcha challenge is returned in previous request

Response Format

The following data elements will be returned in the response. If a 'challenge' is returned, the application must present the information to the user along with the captcha image/audio. Once the user enters the captcha word, send the 'getConsent' request again with the required parameters along with the user entered captcha word and context.

  • statusText -- contains the message that needs to be displayed to the user regarding the permission that is being granted to the Consumer application
  • challenge -- when user needs to be captcha challenged to get permission to access protected content
    • info -- Free form text to display to the user
    • context -- challenge context to be returned on subsquent getConsent requests
    • url -- Url for obtaining Captcha (Refer to getCaptcha for more information)

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
  • challenge_info
  • challenge_context

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
    • 3015 - Captcha Required/Invalid

Sample Response

XML

         <response xmlns="https://api.login.nina.bz">
              <statusCode>200</statusCode>
              <statusText>OK</statusText>
         </response>

JSON

         {"response":{
             "statusCode":200
             "statusText":"OK",
         }

Query String

statusCode=200&statusText=OK