Written November 2020
For opcode 3, request a refresh token for previously authorized service, the refresh'token$ parameter should contain the value of the "refresh'token" (typically in the form of a name-value pair within a JSON document) in the response$ parameter returned by a prior opcode 1 or 2. For example, a typical response$ JSON document might look something like this...
{
"access_token": "zb29.E0RfWH6SMC2upzYbvBoy31p3Cmtuqr8T...",
"expires_in": 3599,
"refresh_token": "1//0fbpxFnYPChkpGgXIARAAGA8SNwF-L9Ir4eQLxI3KyuoZWRMz9y...",
"scope": "https://www.googleapis.com/auth/analytics",
"token_type": "Bearer"
}
In this case, you would set refresh'token$ to "1//0fbpxFnYPChkpGgXIARAAGA8SNwF-L9Ir4eQL..."
For opcode 1, request authorization URL, you may optionally set this parameter to specify the HTML redirect code that the authorization process will send to the browser upon success and/or failure. The default displays a generic page designed more for developers than users. The format of the parameter must be:
chr(1) + <html-if-allowed> + chr(2) + <html-if-denied> + chr(3) + <app-callback-url>
Each of the three clauses (consisting of the control character followed by the HTML or URL string) is optional, but must be supplied (even if the string is null) if any of the subsequent clauses are specified.
Typically the HTML string would use the meta clause to specify a URL to redirect to, after displaying a brief message, e.g.
refresh'token$ = chr(1) &
+ "<html><head><meta http-equiv='refresh' content='0;url=https://www.yourwebsite.com/access-allowed/'>" &
+ "</head><body>Thank you for allowing access.</body></html>" &
+ chr(2) &
+ "<html><head><meta http-equiv='refresh' content='0;url=https://www.yourwebsite.com/access-denied/'>" &
+ "</head><body>Sorry, access denied.</body></html>"
The URLs should of course reference actual pages you have created or know to exist.
The <app-callback-url> is mainly used with certain OAuth2 services which to not allow for the http://localhost:port callback.
