Using Kore.ai APIs

Kore.ai Bots Platform provides access to bot development using secured APIs. All key developer activities like bot creation, bot import and export, training, and publishing are available using these APIs. Key account management activities like managing Bot Builder access, managing admin and bot roles can also be performed via secured public APIs. For a complete list of APIs and usage instructions refer here.

Authentication of the API requests involves the following two steps:

1. Associate API Scopes to an App: As a first step to allow a client application to access the Bots Platform APIs, you need to associate the client app with the bot. You could create a new app or associate an existing app. As a part of creating the app, you need to select the API scopes for the App, which allows you to provide access to only the selected APIs to the app.
   • Bot Builder API Scopes: Bot developers can define bot specific API Scopes from the Bot Builder tool.
   • Bot Admin Console API Scopes: Account administrators can define API Scopes to access any of the bots built in their accounts from the Admin Console.
2. Generating JWT token: To access Bot Platform’s public APIs, the application making the API request requires authentication. Kore.ai uses the JWT (JSON Web Token) mechanism to handle the authentication. For a quick overview of the JWT token, read Introduction to JWT tokens.
   Use the Client ID and Client Secret of the client app from above to generate a JWT token. This token needs to be passed as a part of each API request for authorization.

Associating API Scopes

Bot Builder

Following steps let you associate API Scopes to a Client App from the Bot Builder:

1. Hover over the side-navigation panel of the bot and click API Extensions.
2. On the Apps & Agents page, click the API Scopes tab and then click New.
3. On the New API Scope Mapping page, from the App drop-down list, select an existing client app for authentication. To create a new app, click the Manage Apps link.
4. Once you select an app, the Client ID and Client Secret section appear. Copy the values.
5. Under the Scopes section, select the APIs for which you want the client app to have access. The apps cannot access the APIs that aren’t selected here.
   

NOTE: Once enabled, the API Scopes need to be Published. Follow the Publish procedure ensuring that the API Scopes are selected from the API Extensions option.

Bot Admin Console

Following steps let you associate API Scopes to a Client App from the Bot Admin Console:

1. On the side-navigation panel of the Bots Admin homepage, click Security & Control > API Scopes.
2. On the API Scopes page, click New.
3. On the New API Scope Mapping page, from the App drop-down list, select an existing client app for authentication. To create a new app, click the Manage Apps link.
4. Once you select an app, the Client ID and Client Secret section appear. Copy the values.
5. Under the Scopes section, select the APIs for which you want the client app to have access.

Generating JWT Token

Once you have associated the API scopes to a client app, you need to generate JWT token for API requests.

1. Go to http://jwt.io and scroll down the page to the Decoded section.
   
2. Replace the contents in the Payload box with the Client ID of the app copied in the previous section.
   
   Note: The Bot Builder validates the token only when it is generated exactly as “appId”. The platform doesn’t validate tokens generated with any other formats such as “App ID” “appid” or “app ID”.
3. In the Verify Signature box, enter the Client Secret copied from the previous section in the box with the text your-256-bit-secret.
   
4. Copy the generated JWT token from the Encoded section on the left.
   
5. This token can be used to access the required API and it needs to be passed as a part of each API request for authorization.
6. You can use the API Collection to test the APIs from your Postman setup. See here for more.