Using AI for Service Platform APIs

The AI for Service platform lets you develop AI Agents using secured APIs. All key developer activities — creation, import and export, training, and publishing — are available via these APIs. Key account management activities like managing XO Platform access, admin, and roles can also be performed via secured public APIs. For a complete list of APIs and usage instructions, refer to the API List.

Authentication involves two steps:

1. Create a JWT App: A client JWT App creates secure authentication credentials to access XO Platform features. Associate the app for BotKit, APIs, SDKs, and Channels.
2. Assign API Scopes to the App: Assigning API scopes allows the app to access Platform APIs securely:
   • XO Platform API Scopes: Assign appropriate scopes to access platform features.
   • Admin Console API Scopes: Account administrators assign scopes to access features in AI Agents built in their accounts.

Creating and Managing JWT Apps in the Platform

1. Go to App Settings > Dev Tools > Web/Mobile SDK.

   

2. If creating a JWT app for the first time, click Add. Alternatively, select Create JWT App from the JWT App drop-down list.

3. On the Create JWT App page, enter a name for the app.

4. Select the JWT Signing Algorithms for Client App Authentication.

5. Select Enforce JTI, JWE, or both as needed:

   • Enforce JTI (JWT ID) Claim: After enabled, the Platform only accepts requests with the JTI Claim; requests without it are rejected.

   • Enforce JWE Encryption: To access the Platform’s public APIs, the application requires authentication. Kore.ai uses the JWT (JSON Web Token) mechanism. For an overview of JWT tokens, see Introduction to JWT tokens.

   • Enforce Request and Response Payload Encryption: Provide the symmetric encryption key used by the Platform to encrypt Public API request and response payloads. Use the same key to decrypt payloads. Refer to How Request and Response Payload Encryption Works.

   

6. Select Next and Done.

7. Select the app name from the JWT App drop-down to see the app’s details (App name and ID, Client ID and Secret).

Use the Client ID and Client Secret of the client app to generate a JWT token. Pass this token in each API request for authorization.

How Request and Response Payload Encryption Works

When the Enforce Request and Response Payload Encryption option is enabled, you must provide a public key. The platform generates a secure AES-256 encryption key to encrypt the public API request payload. The server receives the encrypted request, processes it, and returns the encrypted response payload along with the AES key encrypted with the client’s public key. Only the client that owns the matching private key can decrypt the AES key and access the original data.

The request and response payload encryption option is supported for the following endpoints in the App Builder:

• Session History
• Get Analytics
• Get Conversation Details
• Get All Conversation Data Call Details
• LLM and Generative AI Usage Logs API

When you enable this option, the platform:

1. Accepts the client’s public key for the JWT app.
2. Generates a secure AES-256 encryption key.
3. Encrypts request and response payloads using AES-256 key.
4. Encrypts (wraps) the AES-256 key with the client’s public key.
5. Returns the encrypted response payload, the protected AES key, and related metadata.
6. The client uses its private key to decrypt the AES key, then decrypts the original payload.

Creating and Managing Apps in Admin Console

1. Log in to the Admin Console.
2. Go to Security & Control > API Scopes.
3. On the API Scopes page, click New.
4. Click the Manage Apps link to create a new app.
5. Click New App and then:
   1. Enter a name.
   2. Select Enforce JTI, JWE, or both as needed.
6. Click Save and Done.

Supported APIs for Encryption in the Admin Console

The request and response payload encryption option is supported for the following endpoints:

• Session History
• Get User Information
• Get User Roles Details
• Create Users
• Update User
• Update User Access
• Delete Users
• LLM and Generative AI Usage Logs API
• Conversation Details and Summary API

Data Tables

Access control from the Data Tables module is different from the Platform and Admin Console access controls.

You can define apps to securely access data from data tables and views:

• Create one or more apps. Learn more.
• Apps can be used for:
  • Accessing data tables and views over public APIs.
  • Accessing data tables and views using Service Node.
  • Accessing the export and import API for data table and view definitions.
• Grant the app read, write, and delete permissions to each table and view separately. Learn more.

Associating API Scopes

After creating a client JWT app, associate it with API scopes.

Adding API Scopes in the XO Platform

1. Go to App Settings > Dev Tools > API Scope and click Create API Scope.

2. On the New API Scope Mapping page, from the JWT App drop-down list, select an existing client app.

3. Copy the Client ID and Client Secret displayed on the screen.

4. Select the appropriate Automation or Contact Center scopes to allow access to the respective APIs.

5. Click Save.

Adding API Scopes in the Admin Console

1. Log in to the Admin Console.

2. Go to Security & Control > API Scopes.

3. On the API Scopes page, click New.

4. From the App drop-down list, select an existing client app.

5. Click Manage Apps to create a new app.

6. After selecting an app, copy the Client ID and Client Secret.

7. Under the Scopes section, select the appropriate scopes to allow access to the respective APIs. Learn more.

8. Click Save. The app and associated scopes are listed on the API Scopes page.

9. To delete an app and its associated API Scope, click the Delete icon.

List of Available API Scopes

SCOPE	DESCRIPTION
Intent and Entity Detection	Assign this scope to allow intent and entity detection from an utterance using secured APIs.
User Engagement Trend	To retrieve the user engagement trend.
Batch Tests Execution	To execute Batch Test Suites and get results.
Batch Tests Management	To create, modify, and delete Batch Test Suites and results.
Chat History	Assign this scope to retrieve chat transcripts using secured APIs.
Debug Logs	Assign this scope to retrieve debug logs using secured APIs.
Bot Export	Export definition of a selected agent.
Import Variables	Assign this scope to import variables using secured APIs.
Export Variables	Assign this scope to export variables using secured APIs.
Proactive Messages	To proactively send messages to end-users via supported channels.
Train ML	To match a given utterance against the NL model to identify intents and entities.
Train FAQ	To match a given FAQ against the FAQ model.
Utterances Import	To import utterances for a task.
Utterances Export	To export utterances for a task.
Logs History	To retrieve the change logs for the particular AI Agent.
Bot Sessions	Assign this scope to retrieve conversation sessions.
Billing Sessions	Assign this scope to retrieve billing sessions.
Custom Reports	To retrieve data associated with custom widgets and reports.
RCS Message Events	Assign this scope for opting in users to RCS Business Messaging and sending broadcast messages.
Metrics	Assign this scope to retrieve Metrics information related to Intents Found, Intents not Found, Failed Tasks, Successful Tasks, and Performance Logs.
Manage Knowledge Graph	To export the complete definition of the Knowledge Graph.
NLP Configurations	Assign this scope to update NLP thresholds and configurations.
Update FAQs	Assign this scope to update FAQ Responses and FAQ Status.

After enabled, the API Scopes must be Published. Follow the Publish process to ensure that the API Scopes are selected.

Generating the JWT Token

After associating API scopes with a client app, generate the JWT token for API requests.

1. Visit https://developer.kore.ai/tools/jwt/.

2. In the Algorithm drop-down list, select HS256.

3. Scroll down to the Decoded section, and update the Payload and the Secret.

4. Replace the content of the Payload field with the code block below, adding the Client ID of the app:

   {
       "sub": "1234567890",
       "appId": "add-Client-ID-here"
   }
   

   The Platform validates the token only when it is entered exactly as “appId”. Do not use “App ID”, “appid”, or “app ID”.

5. In the Verify Signature field, replace your-256-bit-secret with the Client Secret.

6. Click Copy JWT to copy the generated token. Pass this token in the API request for authorization.

---