Protocols/WebAPI/Auth/Client/getConsent

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