Xbase++ Requires Chilkat v11.0.0+

Using the OAuth2 Authorization Token in REST API Calls

See more OAuth2 Examples

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

LOCAL nSuccess
LOCAL oJson
LOCAL cAccessToken
LOCAL oHttp
LOCAL cResponseStr
LOCAL oReq
LOCAL oResp
LOCAL oRest
LOCAL oSbAuthHeaderVal

nSuccess := 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 ----
oJson := CreateObject("Chilkat.JsonObject")
nSuccess := oJson:LoadFile("qa_data/tokens/myToken.json")
IF (nSuccess == 0)
    ? oJson:LastErrorText
    oJson:destroy()
    RETURN
ENDIF

//  Get the access_token member.
cAccessToken := oJson:StringOf("access_token")

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

//  Setting the AuthToken property causes the "Authorization: Bearer <token>" header to be added to each request.
oHttp:AuthToken := cAccessToken

//  For example:
cResponseStr := oHttp:QuickGetStr("https://example.com/someApiCall")

//  Another example:
oReq := CreateObject("Chilkat.HttpRequest")

oReq:HttpVerb := "POST"
oReq:ContentType := "application/x-www-form-urlencoded"
//  ...

oResp := CreateObject("Chilkat.HttpResponse")
nSuccess := oHttp:HttpReq("https://example.com/someApiCall", oReq, oResp)
IF (nSuccess == 0)
    ? oHttp:LastErrorText
    oJson:destroy()
    oHttp:destroy()
    oReq:destroy()
    oResp:destroy()
    RETURN
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 ----
oRest := CreateObject("Chilkat.Rest")

nSuccess := oRest:Connect("example.com", 443, 1, 1)
//  ...

//  Set the Authorization property to "Bearer <token>"
oSbAuthHeaderVal := CreateObject("Chilkat.StringBuilder")
oSbAuthHeaderVal:Append("Bearer ")
oSbAuthHeaderVal:Append(cAccessToken)
oRest:Authorization := oSbAuthHeaderVal:GetAsString()

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

//  For example:
cResponseStr := oRest:FullRequestNoBody("GET", "/someApiCall")

oJson:destroy()
oHttp:destroy()
oReq:destroy()
oResp:destroy()
oRest:destroy()
oSbAuthHeaderVal:destroy()