(Visual FoxPro) Using the OAuth2 Authorization Token in REST API Calls

Demonstrates how to use an OAuth2 authorization token in REST API calls after obtaining it.

Note: This example requires Chilkat v11.0.0 or greater.

Chilkat ActiveX Downloads ActiveX for 32-bit and 64-bit Windows

LOCAL lnSuccess
LOCAL loJson
LOCAL lcAccessToken
LOCAL loHttp
LOCAL lcResponseStr
LOCAL loReq
LOCAL loResp
LOCAL loRest
LOCAL loSbAuthHeaderVal

lnSuccess = 0

* This example assumes the Chilkat API to have been previously unlocked.
* See Global Unlock Sample for sample code.

* This example demonstrates how to include the OAuth2 authorization token in HTTP requests (REST API calls).
* An OAuth2 authorization token is typically in JSON format, and looks something like this:

* {
*   "token_type": "Bearer",
*   "scope": "openid profile User.ReadWrite Mail.ReadWrite Mail.Send Files.ReadWrite User.Read Calendars.ReadWrite Group.ReadWrite.All",
*   "expires_in": 3600,
*   "ext_expires_in": 3600,
*   "access_token": "EwCQA8l6...rW5az09bI0C",
*   "refresh_token": "MCZhZ...6jBNRcpuQW",
*   "id_token": "eyJ0eXAi...kcuQQrT03jMyA",
*   "expires_on": "1569281808"
* }

* A few notes about the JSON above:
* 
* 1) Different OAuth2 implementations (servers) may have different JSON members. 
*    The important ones for this discussion are "access_token" and "refresh_token".   
*    These members should always be named exactly "access_token" and "refresh_token".  
*    (I've never seen them named differently, although I don't think it's a formal standard.)
* 
* 2) The "id_token" is present if you obtained the OAuth2 authorization token including "openid" in the scope.
*    It contains information about the user.  It is a JWT (per the OIDC specification) and here is the Chilkat
*    example for decoding the id_token.
* 
* 3) If you don't have a "refresh_token" in your JSON, some REST API's require "offline_access" to be included
*    in the scope when obtaining the OAuth2 token.
* 
* 4) IMPORTANT: Quite often, access_token's are only valid for a limited amount of time.  (Often just 1 hour (i.e. 3600 seconds)).
*    When the access token expires, your HTTP request will fail with a 401 Unauthorized status response.  This is where your application
*    can automatically recover by fetching a new access_token and re-sending the request.  I'll explain...  
*    Usually getting an OAuth2 token for a user requires interactive approval from the user in a browser.
*    However, refreshing the access_token does NOT require user interaction.  You should design
*    your application to automatically recover from an expired access token by 
*    (A) Automatically fetch a new access_token using the refresh_token as shown in this example.
*    (B) Persist the new JSON to wherever you're storing the access token, such as in a file or database record.  You'll need it for the next time you refresh.
*    (C) Update the http.AuthToken or rest.Authorization property (as shown below)
*    (D) Re-send the request using the updated auth token.
*    The above 4 steps (A, B, C, D) can be automatic such that the user never notices, except for a small delay in performance.

* When your application obtains the OAuth2 access token, it should store the JSON in persistent manner, such as in 
* a file, a database record, etc.  The "access_token" is used by your application when sending REST requests.  Typically, it is sent
* in the Authorization request header.  For example:
* 
* Authorization: Bearer <token>
* 

* -----
* Chilkat has two classes for sending HTTP requests.  One is named "Http" and the other is named "Rest".  Either can be used.  
* Once you become familiar with both, you'll find that some requests are more convenient to code in one or the other.
* 
* I'll demonstrate how to get the access_token from the JSON and add the Authorization header for both cases.
* 

* ----
* ---- (1) Get the access_token ----
loJson = CreateObject('Chilkat.JsonObject')
lnSuccess = loJson.LoadFile("qa_data/tokens/myToken.json")
IF (lnSuccess = 0) THEN
    ? loJson.LastErrorText
    RELEASE loJson
    CANCEL
ENDIF

* Get the access_token member.
lcAccessToken = loJson.StringOf("access_token")

* ----
* ---- (2) Demonstrate adding the "Authorization: Bearer <token>" header using Chilkat Http ----
loHttp = CreateObject('Chilkat.Http')

* Setting the AuthToken property causes the "Authorization: Bearer <token>" header to be added to each request.
loHttp.AuthToken = lcAccessToken

* For example:
lcResponseStr = loHttp.QuickGetStr("https://example.com/someApiCall")

* Another example:
loReq = CreateObject('Chilkat.HttpRequest')

loReq.HttpVerb = "POST"
loReq.ContentType = "application/x-www-form-urlencoded"
* ...

loResp = CreateObject('Chilkat.HttpResponse')
lnSuccess = loHttp.HttpReq("https://example.com/someApiCall",loReq,loResp)
IF (lnSuccess = 0) THEN
    ? loHttp.LastErrorText
    RELEASE loJson
    RELEASE loHttp
    RELEASE loReq
    RELEASE loResp
    CANCEL
ENDIF

* In both of the above cases, the "Authorization: Bearer <token>" header is automatically added to each request.

* ----
* ---- (3) Add the Authorization header using Chilkat Rest ----
loRest = CreateObject('Chilkat.Rest')

lnSuccess = loRest.Connect("example.com",443,1,1)
* ...

* Set the Authorization property to "Bearer <token>"
loSbAuthHeaderVal = CreateObject('Chilkat.StringBuilder')
loSbAuthHeaderVal.Append("Bearer ")
loSbAuthHeaderVal.Append(lcAccessToken)
loRest.Authorization = loSbAuthHeaderVal.GetAsString()

* All requests sent by the rest object will now include the "Authorization: Bearer <token>" header.

* For example:
lcResponseStr = loRest.FullRequestNoBody("GET","/someApiCall")

RELEASE loJson
RELEASE loHttp
RELEASE loReq
RELEASE loResp
RELEASE loRest
RELEASE loSbAuthHeaderVal