Access Tokens

Introduction

Access tokens are built with a scope of time and permissions, enabling you to control what your end users can do and for how long in the client applications you deploy that talk to the Kallo API directly.

Unlike API keys, access tokens:

• Have a finite lifetime (i.e. they expire)
• Provide only the level of access deemed necessary by your application logic
• Are designed to be distributed for use within your web, mobile, and desktop apps

When to Use

Use access tokens whenever:

1. You are using a Kallo SDK that renders a UI component in your end user app
2. Your end user app communicates directly with any Kallo API, including REST and WebSocket APIs

When Not to Use

Access tokens are not necessary when your back end services are communicating with a Kallo API directly. Keep in mind any such operation must then involve authentication and authorization that you build and implement to prevent unauthorized use of your API key.

Format

Unlike API keys, all access tokens are JSON Web Tokens JWTs. Each JWT obtained from the Kallo API is already Base64-encoded and thus should never necessitate any decoding or dissection of the data contained within.

How to Use

Step 1: Obtain the JWT String

See our example below.

Step 2A: With an API Request

After obtaining a JWT from the Kallo API, it can be passed as-is to the client application for use in requests to any Kallo API.

If your app is using a Kallo SDK, simply supply the JWT string to the appropriate SDK input.

If your app uses custom code, ensure your app includes a Bearer token in the Authorization header of requests to any Kallo REST API:

Authorization: Bearer <TOKEN>

In the above example, replace the entirety of <TOKEN> with the JWT string.

Step 2B: With the Kallo SDK

Any reference you see to accessToken in the SDK refers to the <TOKEN> value described above ⤴. Simply provide the JWT string wherever the SDK is expecting it as an input.

End User Identity

There are two different methods for defining which user ID will become associated with all activity performed by the end user who utilizes an access token in your app.

Method 1: Shared Identify

With shared identity, Kallo will not store any distinguishing identifiers for each of your end users. Instead, all actions will be treated as if the account used to generate the access token is the same as the account performing the actions.

Usage

To utilize shared identity, supply the user ID of the account to which the API key used to generate the access token belongs in the access token creation request. For example, if you (the developer) have user ID 75d219d3-331e-4b12-8d47-1d1223857256, then the request body for creating an access token (see POST /access-tokens) should identify you as the user:

{
  "userId": "75d219d3-331e-4b12-8d47-1d1223857256",
  "scopeObjects": [
    {
      "id": "f3ee8b67-ef8f-49ca-b7d4-33e9cfa05ad9",
      "type": "convo",
      "role": "participant"
    }
  ],
  "expiresAt": "2024-05-30T15:39:00Z"
}

Reference: POST /access-tokens

Benefits

• Easier, more rapid integration
• Your end users' interactions will be easily accessible from within the Kallo app itself (because they are stored as if they were your own interactions)
• Although Kallo does not resell or perform any identifying analysis on user interactions, for apps that require a high level of privacy/security control, this may be the preferable route

Considerations

• User context features will not work
• Your code will need to keep track of which users performed which actions, if necessary. For example, to resume a convo from the past, your code and database will need to handle and store several object IDs for different types of objects to ensure proper access by your end users to only the convos they are entitled to access.
• High volumes of interactions from your users may impact your own usage of the Kallo app because those interactions will appear as if they were your own

Method 2: Unique Identity

With unique identity, Kallo will generate a unique ID for each of your users.

Usage

To utilize unique identity, supply the user ID of the user created within your org (including users within your company and/or end users your company serves) for whom you want to provision access by means of an access token. Unlike the shared identity method, you should not supply your own user ID (i.e. the one associated with the API key) unless you actually want to provision the access token for your user.

Benefits

• Your users' data will be cleanly segregated
• Kallo keeps track of who, exactly, can access what, exactly
• Seamless integration of your org's internal users with the Kallo app, for scenarios where you are generating access tokens to serve an internal app and your org license provides Kallo app access to your internal users
• User context features

Considerations

• You must first create an org (organization object), which requires org-based licensing
• You must create one unique Kallo user for each of your users and keep track of each respective user ID association in your own database
• More work required to access interactions by your end users

Flows

Two primary flows exist to keep access control fully within the control of the integrating system:

1. Creation
2. Revocation (optional)

Creation

When implementing a component from a Kallo SDK or within a custom front-end application that needs to talk to a Kallo API directly, you should create an access token.

Request

curl -X POST https://api.kallo.ai/access-tokens \
     -H "Authorization: Bearer api-key.KkEeYy1234FfAaKkEe5678" \
     -H "Content-Type: application/json" \
     -d '
        {
          "userId": "bef7ca66-88f6-436a-a4f9-6713a5a2c42a",
          "scopeObjects": [
            {
              "id": "723752ed-8553-4756-9c3d-10a7ec77a83b",
              "type": "convo",
              "role": "participant"
            }
          ],
          "expiresAt": "2024-05-30T15:39:00Z",
          "allowOrigin": "*"
        }
        '

In the above example, if the request is successful, the resulting access token will:

• Give access to convo with ID 0aac52b0-7c1e-4f39-87d4-25c4e3da8a60 with participant-level rights
• Authenticate the end user as Kallo user with ID e57516c7-5511-4654-8083-e1eee794e0c9
• Automatically expire at 2024-05-30T15:39:00Z

Reference: POST /access-tokens

Response

The response for the above request, if successful, would be served with a 201 status code and look something like this:

{
  "id": "c3b80ad0-41c9-419c-9340-a1e20eeeba94",
  "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MTcwODM1NDAsImlhdCI6MTcxNzA4MzQ4NiwiaXNzIjoiYXBpLmthbGxvLmFpIiwianRpIjoiYzNiODBhZDAtNDFjOS00MTljLTkzNDAtYTFlMjBlZWViYTk0Iiwic2NvcGUiOiJjb252bzo3MjM3NTJlZC04NTUzLTQ3NTYtOWMzZC0xMGE3ZWM3N2E4M2IjcGFydGljaXBhbnQiLCJzdWIiOiJiZWY3Y2E2Ni04OGY2LTQzNmEtYTRmOS02NzEzYTVhMmM0MmEifQ.LndQAFKPae5SmCwsxvlylMHC-SbbLangBwGA_Be6kepZhEH5gfS3gZ04-d7bu-eNsdju7kB5S3T7g7R3YVYlUDZPQMai2bJmSbpIG7Z5gc77CXvNkk-wRhUWOIfiEnRh5FB9fVC06XteW1AqWnWT7qbhPID35NeNgPS5jQPX8zzXaIM67kEDHkq1HllKwgbWvLC3O-W7aiDgSIhuHvE86kYn3N0mUt1OttlZmuBEPv2nuTCLnAhb7v1BMTvL7OyH9_k9itrvW5VappdZjYXgoJWe8oO6CJZ-DcUg6CI-RD30SNBFjzINPvJT4bx5skJXmcrn_A1vNetTkCcYeX0geg"
}

In this response:

• id is the ID of the access token; you should retain this if you want to potentially revoke the token later
• jwt is the JWT bearer token and can be used in your client-side applications to communicate directly with any Kallo API

Revocation

Although access tokens automatically expire at a predetermined time, you may face situations where it is necessary to revoke a token before its scheduled expiration time.

Request

curl -X GET https://api.kallo.ai/access-tokens/c3b80ad0-41c9-419c-9340-a1e20eeeba94 \
     -H "Authorization: Bearer api-key.KkEeYy1234FfAaKkEe5678" \

In the above example, if the request was successful:

• The access token with ID c3b80ad0-41c9-419c-9340-a1e20eeeba94 will be revoked and will no longer work prior to expiration
• Note that the API key used is associated with the same user as the API used in the request that originally created the access token. Whether the API key itself is the same or not, it is essential that the API key used is associated with the same user as the API key used in the creation request, or the revocation request will fail.

Reference: DELETE /access-tokens/{accessTokenId}