This post will explore the types / categories of authentication tokens that are used in Kaizala APIs. Most of it has been explained on a course on Microsoft Virtual Academy – recommend you to checking that out here. In case you are new to Kaizala APIs, you could read this post as a pre-read.
Kaizala Service uses a token based authentication mechanism. Any API call you make requires an access token in the headers and it carries the information required to access the resource (for more information refer the documentation). In the next few sections, we will see the different kinds of tokens.
Types of Tokens
While developing / integrating with Kaizala Service, you will encounter 2 types of tokens:
- Refresh token
- Access token
The Refresh Token has information to required to generate an access token. The only purpose of a refresh token is to generate an access token. (Hence cannot be used for accessing APIs).
The Access Token has information required to access a resource / API endpoint. (and is passed while accessing a resource / API endpoint)
Categories of Tokens
There are two categories of tokens based on how they were acquired / privileges they have, namely: Group and User level tokens.
1) Group Token
Group level token is generated from the Kaizala Management Portal by associating a connector with a group. This token allows only those operations to be performed within the context of the particular group. Its very suitable for scenarios where you want to limit access to a particular group and want a way to invalidate the token. On associating a connector with a group, a pop-up with the refresh token appears. Copy the token and save it. (Note: The token generated here is the refresh token and will need to generate the access token before calling into Kaizala)
Hitting the regenerate button will invalidate the refresh token that was previously generated.
2) User Token
Kaizala tokens that allow access with the context of the user are called user tokens. There are a bunch of ways to generate user tokens.
2.1) Generate user token programmatically / using API (non-tenant user token)
The user token can be generated by using API by generating the PIN / OTP by providing the mobile number and subsequently using the OTP to generate the refresh token.
(Refer steps 1, 2 & 3 under section 1.1 in the Kaizala API Postman collection here)
2.2) Generate tenant user token from portal
A tenant user token can be generated from the portal by going to a particular connector and hitting the Generate user token button. (Note: the token displayed here is the refresh token).
Tenant admin vs. Non-Tenant admin tokens
Based on the user generating the token its either a tenant admin / non-tenant admin token. For instance, if the token was generated by a tenant admin, the resulting token would be a tenant admin token. You can verify the token details by calling into the below endpoint ( below example is with a non-tenant user token ):
2.3) Generate user token programmatically using OAuth (non-tenant token)
A non-tenant user token can also be generated using OAuth. For details on Kaizala Oauth, refer the Kaizala documentation here.
2.4) Generate tenant user token programmatically using OAuth
A tenant token can be generated programmatically using the OAUTH approach. This involves marking the connector with Enable AAD OAuth. This will enable the AAD authentication along with the Kaizala authentication.
(For more details on Kaizala OAuth, refer the Kaizala documentation here.)
2.5) Generate Integration Service Token
An Integration Service Token is a token fetched from the client side using the KASClient SDK API – getIntegrationServiceToken. This is used to authenticate a web request from Kaizala Action to a 3rd party web service. For more details on this, refer the post: Securing API requests from Kaizala action.
2.6) Generate bot token
A bot token is used to communicate / send messages with the bot’s identity. For details on how this is done, you can refer to the post, Adding bot support to a Kaizala group.
Generating an access token
In case you are not familiar with how to generate an access token, its done by hitting the below endpoint
Kaizala tokens could be generated programmatically from Kaizala service through APIs / OAuth or manually from the portal. On the client side, the Integration Service Token could be generated using the getIntegrationServiceToken API in KASClient SDK.
Hope the post was helpful. Give me your feedback, thoughts / comments through the Contact page.