Difference between revisions of "Protocols/WebAPI/Auth/Client/getConsent"
m (AD moved page Protocols/WebAPI/Auth/getConsent to Protocols/WebAPI/Auth/Client/getConsent without leaving a redirect) |
|||
(2 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
{{Protocols/WebAPI}} | {{Protocols/WebAPI}} | ||
− | This page is about the getConsent method for [[Protocols/WebAPI/Auth|WebAPI | + | This page is about the getConsent method for [[Protocols/WebAPI/Auth/Client|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. | 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 == | == Initial Request == | ||
− | |||
− | |||
* URL | * URL | ||
Line 17: | Line 17: | ||
*** your developer Id required to access NINA APIs | *** your developer Id required to access NINA APIs | ||
** f (required) | ** f (required) | ||
− | *** the required format of the response ( | + | *** the required format of the response (XML, JSON, or the query string) |
** enc (required) | ** 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. | *** 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. | ||
Line 41: | Line 41: | ||
** url -- Url for obtaining Captcha (Refer to getCaptcha for more information) | ** url -- Url for obtaining Captcha (Refer to getCaptcha for more information) | ||
+ | === The XML standard wrapper === | ||
+ | <pre> | ||
+ | <response> | ||
+ | <statusCode /> | ||
+ | <statusText /> | ||
+ | <statusDetailCode /> | ||
+ | <requestId /> | ||
+ | <data> | ||
+ | .... | ||
+ | </data> | ||
+ | </response> | ||
+ | </pre> | ||
+ | |||
+ | === The JSON standard wrapper === | ||
+ | <pre> | ||
+ | {"response":{ | ||
+ | "statusCode":"" | ||
+ | "statusText":"", | ||
+ | "statusDetailCode":"" | ||
+ | "requestId":"" | ||
+ | "data":{ | ||
+ | .... | ||
+ | } | ||
+ | }} | ||
+ | </pre> | ||
+ | |||
+ | === 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 ==== | ||
+ | <pre> | ||
+ | <response xmlns="https://api.login.nina.bz"> | ||
+ | <statusCode>200</statusCode> | ||
+ | <statusText>OK</statusText> | ||
+ | </response> | ||
+ | </pre> | ||
+ | |||
+ | ==== JSON ==== | ||
+ | <pre> | ||
+ | {"response":{ | ||
+ | "statusCode":200 | ||
+ | "statusText":"OK", | ||
+ | } | ||
+ | </pre> | ||
+ | ==== Query String ==== | ||
+ | <pre> | ||
+ | statusCode=200&statusText=OK | ||
+ | </pre> | ||
[[Category:Stub]] | [[Category:Stub]] | ||
Line 47: | Line 127: | ||
[[Category:AIM]] | [[Category:AIM]] | ||
[[Category:Protocols/WebAPI]] | [[Category:Protocols/WebAPI]] | ||
+ | [[Category:Protocols/WebAPI/Auth]] | ||
+ | [[Category:Protocols/WebAPI/Auth/Client]] | ||
[[Category:Work_In_Progress]] | [[Category:Work_In_Progress]] |
Latest revision as of 22:54, 25 March 2020
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.
Contents
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
- devId (required)
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