Requiring Authentication

Here, we walk through the simplest possible way to configure an Airkit application so that it requires authentication in order to be inserted into existing web page using the SDK.

Org-Level Configurations

Creating a New Token

New tokens are created in Console > API > Tokens by clicking on the Create New button to the upper right. To finish creating the token, give the token a unique name and click the Create button to the bottom right of the Inspector:

This will open the newly-generated Secret in the Inspect. Note that the Secret in the following example is greyed out for security purposes:

This is the one and only time the Airkit platform will share the Secret with you, so make sure you take note of it and store it somewhere safe.

Configuring a Custom Integration

Toggle over to Console > Integrations > Custom Integrations . Click on the Create New button to the upper right.

Define the Integration Name and Key as something relevant and intuitive, then configure the following fields as follows:

  • Properties > Authentication Type - API Token
  • Auth Toke > Token Parameter Type - Header
  • Token Parameter Name - Authorization
  • Token Parameter Value Template - Bearer {token}

Click the Create button to the bottom right to finalize this token as a Custom Integration. You should see it appear in the Stage upon creation.

Configuring a Connected Account

Toggle over toConsole > Integrations > Connected Accounts . Click on the Create New button to the upper right.

Give the account a relevant and intuitive Account Name. Under Integration, select the Custom Integration you just created. Under API Token, enter the Secret you saved upon token creation.

Configuring the Application

Open the relevant app in Studio and toggle over to Settings. Under API Key Filtering, select your configured token to establish it as an available API Key.

Toggle over to the Triggers Builder and select your SDK API. Check Require Authentication and then select configured key from the Select API Key Group dropdown.

Save and publish your application. It is now ready to be inserted into an existing web page – but only if that web page presents the required token for authorization.

Configuring your Website

In order to embed this application in an existing web page, the web page will need to present the required token Secret. The expected format was defined when creating a Custom Integration: the token parameter must be passed in the Header, under the attribute name "Authorization", in the format "Bearer {token}", where "{token}" is replaced by the Secret provided and saved upon token creation.

The following block of HTML would technically embed your application into an exiting web page, provided you replaced SDK_API_URL with the SDK endpoint and TOKEN_PARAMETER_VALUE with your token Secret, given in the form "Bearer {token}":

<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta charset="utf-8" />
    <title>Airkit web SDK</title>
  </head>
  <body>
    <div id="airkit-sdk"></div>
    <script src="https://client.airkit.com/websdk/1.0/airkit_sdk.js"></script>
    <script>
      const sdk = new window.AirkitWebSDK({ renderMode: "inline" })
      sdk.render({ 
        url: SDK_API_URL,
        options: {
            headers: {
                "Authorization": TOKEN_PARAMETER_VALUE
            }
         }
      }) 
    </script>
  </body>
</html>

🚧

Code example only for demonstration purposes

It is not secure to hardcode your token directly into your HTML the way shown above. In practice, you will need to hide the token until making the call to the SDK API.