(Unicode C) Using the OAuth2 Authorization Token in REST API Calls

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

Chilkat C/C++ Library Downloads
MS Visual C/C++ Linux/CentOS C/C++ Alpine Linux C/C++ MAC OS X C/C++	armhf/aarch64 C/C++ C++ Builder iOS C/C++ Android C/C++	Solaris C/C++ MinGW C/C++

#include <C_CkJsonObjectW.h>
#include <C_CkHttpW.h>
#include <C_CkHttpRequestW.h>
#include <C_CkHttpResponseW.h>
#include <C_CkRestW.h>
#include <C_CkStringBuilderW.h>

void ChilkatSample(void)
    {
    HCkJsonObjectW json;
    BOOL success;
    const wchar_t *accessToken;
    HCkHttpW http;
    const wchar_t *responseStr;
    HCkHttpRequestW req;
    HCkHttpResponseW resp;
    HCkRestW rest;
    HCkStringBuilderW sbAuthHeaderVal;

    // 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 ----
    json = CkJsonObjectW_Create();
    success = CkJsonObjectW_LoadFile(json,L"qa_data/tokens/myToken.json");
    if (success != TRUE) {
        wprintf(L"%s\n",CkJsonObjectW_lastErrorText(json));
        CkJsonObjectW_Dispose(json);
        return;
    }

    // Get the access_token member.
    accessToken = CkJsonObjectW_stringOf(json,L"access_token");

    // ----
    // ---- (2) Demonstrate adding the "Authorization: Bearer <token>" header using Chilkat Http ----
    http = CkHttpW_Create();

    // Setting the AuthToken property causes the "Authorization: Bearer <token>" header to be added to each request.
    CkHttpW_putAuthToken(http,accessToken);

    // For example:
    responseStr = CkHttpW_quickGetStr(http,L"https://example.com/someApiCall");

    // Another example:
    req = CkHttpRequestW_Create();
    // ...
    resp = CkHttpW_PostUrlEncoded(http,L"https://example.com/someApiCall",req);
    // ...
    CkHttpResponseW_Dispose(resp);
    // 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 ----
    rest = CkRestW_Create();

    success = CkRestW_Connect(rest,L"example.com",443,TRUE,TRUE);
    // ...

    // Set the Authorization property to "Bearer <token>"
    sbAuthHeaderVal = CkStringBuilderW_Create();
    CkStringBuilderW_Append(sbAuthHeaderVal,L"Bearer ");
    CkStringBuilderW_Append(sbAuthHeaderVal,accessToken);
    CkRestW_putAuthorization(rest,CkStringBuilderW_getAsString(sbAuthHeaderVal));

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

    // For example:
    responseStr = CkRestW_fullRequestNoBody(rest,L"GET",L"/someApiCall");


    CkJsonObjectW_Dispose(json);
    CkHttpW_Dispose(http);
    CkHttpRequestW_Dispose(req);
    CkRestW_Dispose(rest);
    CkStringBuilderW_Dispose(sbAuthHeaderVal);

    }