(Delphi DLL) 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 for Delphi Downloads Chilkat non-ActiveX DLL for Delphi Chilkat ActiveX DLL for Delphi * The examples here use the non-ActiveX DLL.

uses
    Winapi.Windows, Winapi.Messages, System.SysUtils, System.Variants, System.Classes, Vcl.Graphics,
    Vcl.Controls, Vcl.Forms, Vcl.Dialogs, Vcl.StdCtrls, Http, HttpResponse, Rest, JsonObject, StringBuilder, HttpRequest;

...

procedure TForm1.Button1Click(Sender: TObject);
var
success: Boolean;
json: HCkJsonObject;
accessToken: PWideChar;
http: HCkHttp;
responseStr: PWideChar;
req: HCkHttpRequest;
resp: HCkHttpResponse;
rest: HCkRest;
sbAuthHeaderVal: HCkStringBuilder;

begin
success := False;

// 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 := CkJsonObject_Create();
success := CkJsonObject_LoadFile(json,'qa_data/tokens/myToken.json');
if (success = False) then
  begin
    Memo1.Lines.Add(CkJsonObject__lastErrorText(json));
    Exit;
  end;

// Get the access_token member.
accessToken := CkJsonObject__stringOf(json,'access_token');

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

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

// For example:
responseStr := CkHttp__quickGetStr(http,'https://example.com/someApiCall');

// Another example:
req := CkHttpRequest_Create();

CkHttpRequest_putHttpVerb(req,'POST');
CkHttpRequest_putContentType(req,'application/x-www-form-urlencoded');
// ...

resp := CkHttpResponse_Create();
success := CkHttp_HttpReq(http,'https://example.com/someApiCall',req,resp);
if (success = False) then
  begin
    Memo1.Lines.Add(CkHttp__lastErrorText(http));
    Exit;
  end;

// 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 := CkRest_Create();

success := CkRest_Connect(rest,'example.com',443,True,True);
// ...

// Set the Authorization property to "Bearer <token>"
sbAuthHeaderVal := CkStringBuilder_Create();
CkStringBuilder_Append(sbAuthHeaderVal,'Bearer ');
CkStringBuilder_Append(sbAuthHeaderVal,accessToken);
CkRest_putAuthorization(rest,CkStringBuilder__getAsString(sbAuthHeaderVal));

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

// For example:
responseStr := CkRest__fullRequestNoBody(rest,'GET','/someApiCall');

CkJsonObject_Dispose(json);
CkHttp_Dispose(http);
CkHttpRequest_Dispose(req);
CkHttpResponse_Dispose(resp);
CkRest_Dispose(rest);
CkStringBuilder_Dispose(sbAuthHeaderVal);

end;