Skip to main content
Back to App Settings OAuth v2 is the new version of the open protocol to allow secure authorization in a standardized manner from web, mobile, and desktop applications. To use this authorization method, you must first register an account with the web application — you will need the log-in credentials for that application to configure the Authorization Mechanism settings.

​
How oAuth v2 Password Grant Type Works

The oAuth v2 Password grant type allows apps to exchange a user’s credentials for an access token.
  1. The Platform redirects the user to a login dialog at the web application.
  2. The user authenticates.
  3. The web application redirects the user back to the XO Platform with an access token.
  4. The Platform validates the access token.
  5. The access token allows the XO Platform to access a protected resource at the provider, on behalf of the user.

​
Configuring oAuth v2 Using Password Grant Type

  1. Open the assistant for which you want to configure an Authorization profile.
  2. From the left menu, click App Settings, then select Dev Tools > Authorization Profiles.
  3. Click New to open the New Authorization Mechanism dialog. Auth profile - Add
  4. In the Authorization Type drop-down list, select oAuth v2 password grant type.
  5. Enter a Name for your authorization, then define the fields to enable it. Define fields to enable auth

​
Defining Tenancy

If required, in the Subdomain section, select Yes if the base URL for a web application or user interface uses a tenant name in the URL. For example, platform is the tenant organization for a web service that uses subdomain-based tenants, such as www.platform.example.com. In the following example configuration, the tenancy URL contains the {tenant} organization placeholder. Defining Tenancy

​
Selecting Authorization Mode

This section defines how authorization is handled for the integration.
  • Allow users to authorize the integration: End users are prompted to authorize the integration during the conversation with AI Agents.
  • Pre-authorize the integration (Recommended): Authorization credentials are provided in advance. This authorization is reused whenever users interact with the AI Agent, eliminating the need for individual authorization.
Auto-Refresh Token Regeneration can be enabled using the provided consent checkbox. When enabled, the platform automatically regenerates the Refresh Token using the stored OAuth credentials. If the Auth Token expires, the Refresh Token is used to generate a new Auth Token. If the Refresh Token itself expires, the platform automatically generates a new Refresh Token (when the checkbox is enabled), without requiring manual intervention.
Auto-regeneration of refresh tokens works only when the User ID and Password are provided in the OAuth v2 Password Grant Type. If these credentials are not configured, the platform cannot regenerate tokens automatically when the refresh token expires.
Authorization Mode

​
Adding Form Fields

If the default username and password fields do not meet your authorization input needs, add custom fields displayed to the end-user by adding authorization IDP form fields. For example, add a PIN code field in addition to the default fields. Click Add Form Fields, then configure the necessary parameters for each field. The following table describes the fields used to define an authorization form field.
FIELD NAMEDESCRIPTION
Title of FieldSpecify the name of the field displayed to the end-user in the authorization dialog.
Field KeyThe value represents the end-user input value to the authorizing service.
Help HintThe help text displayed in the field to describe what should be entered.
Field TypeWhen Advanced Options is selected, specify the type of field displayed in the end-user interface to collect user input for the Field Key, one of: Textbox, Password
MandatoryWhen Advanced Options is selected, select if the end-user must define this field to complete the authorization.
Data TypeWhen Advanced Options is selected, specify the type of data expected as input from the end-user, for example, String.
VisibilityWhen Advanced Options is selected, specify if the authorization field should be visible, hidden, or displayed as read-only.
Adding form fields

​
Adding Authorization Fields

By default, authorization fields are configured as part of the header of the request message. If your request requires additional authorization fields or the expected authorization is not part of the header (for example, social security number or PIN), click Add Authorization Fields and define the fields. Adding authorization fields
  1. In the Field Type field, select one of the following depending on where in the request message the authorization fields are required:
    • Header – The assistant expects the authorization fields as part of the header of the request.
    • Payload – The assistant expects the authorization fields as part of the content of the body of the request.
    • Query String – The assistant expects the authorization fields as a query in the body of the request.
    • Path Param – The assistant expects the authorization fields as part of the URL path for the request.
  2. In the Field Key field, enter the name of the field for the selected Field Type.
  3. In the Field Value field, enter the value for the Field Key specified.
  4. Click Done. The new authorization field is added in the Authorization Fields section.

​
Defining the Token URLs

In the Token URL field, optionally define a URL to test the authorization settings from XO Platform before deploying the AI Agent. You can use dynamic fields, path parameter fields, query fields, and so forth, for example: http://{tenant}.example.com/test/{{tokenId}} In the Token URL Method field, select the HTTP request method type for the Token URL: one of PUT, POST, PATCH, DELETE, or GET. In the Token URL Content Type field, select the content type expected from the Token URL: one of JSON, RSS, XML, URL Encoded JSON, CSV, Text, Twitter Encoded JSON, Multipart/Form-data, Multipart/Related, or Oracle ADF. In the Refresh Token URL, enter the refresh token URL if required. For authentication errors, enter the Auth Error Status Code.

​
Access using the Connector

In the Access Using a Connector section, select Yes to enable access for AI Agent using the Kore.ai Connector agent. If your domain has no active Kore.ai Connectors defined, a warning message is displayed to contact the Admin Console System Administrator. Click Save Auth to save the authorization settings and close the New Authorization Mechanism dialog.

​
Testing the Authorization

After saving the authorization, test your authorization definition by clicking Test from the Authorization Profile page. Testing the authorization When you click Test, the Test Authorization dialog is displayed and populated with the URL you specified in the Authorization Check URL section. Click Test to begin the authorization test. Test authorization dialog When validation completes, the Test Authorization dialog closes and the results — either success or failure — are displayed to the right of the Test button. If the authorization fails, the Auth Test Failed message is displayed along with the Headers and Response tabs. Test result