This guide outlines the process of setting up access to eGain Knowledge APIs. It explains how to create a client application, understand the supported authentication flows, and use your credentials to securely access the APIs.
eGain APIs use the industry-standard OAuth 2.0 authorization framework to ensure secure and delegated access. Before you can make any API calls, you must first obtain an access token for your application. This token proves that your application has the right permissions to access the requested resources.
The specific OAuth 2.0 flow you use will depend on your application's architecture and the type of user it is serving.
Before you can authenticate, you must register your application in the eGain Administration Console. This process will generate a unique Client ID and Client Secret, which are the credentials your application will use to identify itself.
Log in to your Administrator Console with a Partition Administrator (PA) account.
Navigate to the Client Application creation screen by going to
Departmentdropdown →Partition→Integration→Client Applicationthen click the (+) Plus button to create a new application..
Provide the required information and click Save:
Name: A unique name for your client application.
Resource Type: The resource type accessible by the client application. The only option available is Global.
- Global
Platform: The platform of your client application. The platform you choose determines which OAuth 2.0 flows are available and how your application should handle its credentials.
- Web Application: Select this for traditional server-side applications that can securely store secrets. These are considered confidential clients and use standard authorization flows.
- Single Page Application (SPA): Select this for browser-based JavaScript applications that run entirely on the client side. Since they cannot securely store secrets, they are considered public clients and must use the Proof Key for Code Exchange (PKCE) flow for enhanced security.
The table below outlines key differences between these platform types:
Feature Single Page Application (SPA) Web Applications (Confidential) Environment Devices (browsers for SPAs) Servers Secret Storage Cannot securely store secrets Can securely store secrets OAuth Flow Authorization Code with PKCE Authorization Code Example Mobile apps, browser-based apps Traditional web apps Security Focus Protecting authorization codes without secrets Protecting client secrets - Redirect URL(s): The URL(s) where users will be redirected after granting or denying permission. The pre-registered endpoint to which the authorization server directs the resource owner's user-agent back to the client. This URL is a critical component of the "Authorization Code" grant type.
- Client Responsibility: As the client, you must provide and maintain this endpoint. After the resource owner grants authorization, the authorization server will issue an authorization_code by appending it as a query parameter to the redirect URL.
- Client ID: The Client ID of this client application will be automatically generated after configuration for client application is saved.
- Post Logout Redirect URL: The URL where users are redirected after they sign out of the application.
- Client On-Behalf-Of Flow: Select this checkbox to allow the client application to request tokens on behalf of a user or customer so the app can call APIs using their identity without requiring additional authentication.
- When enabling this flow, ensure the following permissions are enabled under Knowledge > Delegated from the Permissions tab:
- knowledge.portalmgr.onbehalfof.read: Provides read On-Behalf-Of access to the Knowledge Portal manager.
- knowledge.portalmgr.onbehalfof.manage: Provides write On-Behalf-Of access to the Knowledge Portal manager.
- When enabling this flow, ensure the following permissions are enabled under Knowledge > Delegated from the Permissions tab:
- Token Exchange Grant Type: Select this checkbox to enable the ability to exchange an existing token from an external Identity Provider (e.g., Okta, Azure AD) for an eGain access token.
- Access Token Expiry Time: This setting becomes available when Token Exchange is enabled. It allows you to define the validity period for the exchanged token. If left unconfigured, the default expiry is 1 hour.
Generate Client ID and Secret:
- A Client ID will be automatically generated.
- Generate a Client Secret by clicking the
(+)button at the end of the secret table.
Important: A Client Secret is only displayed once upon creation. Copy it and store it in a safe and secure location.
Grant Permissions (Scopes):
- Navigate to the Permissions tab for your client application.
- Grant the appropriate scopes required to call the APIs you intend to use. Scopes define the specific permissions your application has.
- Delegated Permissions: Used when the app acts on behalf of a user.
- Interactive (User/Customer flows): Requires the user to manually log in to provide an authorization code via authorization flow. (e.g.,
knowledge.portalmgr.read/manage). - On-Behalf-Of (OBO) flow: Allows the app to act for a user without an authorization flow. (e.g.,
knowledge.portalmgr.onbehalfof.read/manage).- This flow allows a Client App to obtain a token that carries a user context. Because the token represents a specific user, you must assign and request Delegated Permissions for this flow to function correctly.
- Interactive (User/Customer flows): Requires the user to manually log in to provide an authorization code via authorization flow. (e.g.,
- Application Permissions (Client Credentials flow): Used for where no user is required; the application acts as its own identity.
For a detailed list of which scopes are required for each API, please refer to the developer portal at
https://apidev.egain.com/developer-portal/.
Important: Assigning vs. Requesting Scopes
Assigning permissions in the Administrator Console makes them available, but they are only included in your access token if explicitly requested in your API call.
Once your client application has been created, you can find all the necessary endpoints for authentication. On the client application page within the Administrator Console, click the Metadata button.
This will provide you with the following crucial values:
- Authorization URL: The endpoint to redirect users to for authorization.
- Token URL: The endpoint to exchange an authorization code for an access token or to use the client credentials flow.
- Domain URL: The base URL for your eGain instance.
- Meta URL: The URL for your eGain instance where this metadata can be accessed.
Example API Endpoints Metadata: 
Domain Usage Note: The domain used to request access tokens is https://ai.egain.cloud/, but the domain for calling the actual APIs is https://api.ai.egain.cloud/. Ensure you update the base URL in your application logic once you have received your token.
Authentication is handled based on three distinct personas. The persona determines which OAuth 2.0 flow you must use.
- User: An eGain agent or user acting on their own behalf. This persona uses the Authorization Code flow or Authorization Code flow with PKCE.
- Customer: An end-user of your services who logs in. This persona also uses the Authorization Code flow or Authorization Code flow with PKCE.
- Client App: The application itself, acting on its own behalf for server-to-server integrations or acting on behalf of a User/Customer. This persona uses the Client Credentials flow or On-Behalf-Of flow.
The following sections provide detailed instructions for implementing each of the supported OAuth 2.0 flows.
Important: Matching Flows to Scopes To avoid authorization errors, your Authentication flow must match the "Persona" of the scope you are requesting:
- Client Credentials Flow: Use this only for Application scopes (e.g., app.knowledge.portalmgr.read). While it can technically request Delegated scopes, the resulting token will lack a user context, causing APIs requiring user/customer identity to fail.
- User/Customer Flows: Use these only for Delegated scopes (e.g., knowledge.portalmgr.read). These flows cannot be used for Application scopes because they lack the necessary client-level authorization.
- The On-Behalf-Of (OBO) Flow: This is a unique "hybrid" flow. It uses a Client App identity but adds a User context. It is designed strictly for On-Behalf-Of delegated scopes (e.g., knowledge.portalmgr.onbehalfof.read).
- Note: An OBO token is specialized; it can only call APIs that support On-Behalf-Of authentication. It cannot be used additionally to call required User or Customer identity APIs.
- External Identity Provider (IDP): A user who has already authenticated via a third-party service (like Okta). This persona uses the Token Exchange Flow to "swap" their external token for an eGain-compatible token.
This flow is intended for confidential clients, such as traditional web applications with a secure backend that can safely store a client secret.
The process is divided into two main parts:
Your application needs to redirect the user to the eGain authorization endpoint to get their permission.
Method:
GETEndpoint: Your Authorization URL (from your client application's metadata).
- Example Base Authorization URL for a User:
https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/authorize - Example Base Authorization URL for a Customer:
https://ai.egain.cloud/system/auth/TMPRODB88619984-C/oauth2/authorize
- Example Base Authorization URL for a User:
Query Parameters:
| Parameter | Relevance | Description |
|---|---|---|
client_id | Required | The Client ID for your application. |
response_type | Required | Must be set to code. |
redirect_uri | Required | The URL where the user will be redirected. This must exactly match one of the URLs you registered. |
scope | Required | A space-separated list of scopes. You can include any combination of scopes assigned to your client application in a single request. This allows you to generate one multi-purpose token for your entire application, or separate tokens for specific tasks, depending on your architectural needs. |
state | Recommended | An opaque value used to prevent cross-site request forgery attacks. |
- Example Full Authorization URL for a User:
https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/authorize?client_id=b4b2c1d9-4c19-4e8a-8e7a-9a0b1c2d3e4f&response_type=code&redirect_uri=https%3A%2F%2Foauth.pstmn.io%2Fv1%2Fcallback&scope=core.aiservices.manage&state=a1b2c3d4e5f67890
After your application receives the authorization code, it must send a POST request to the token endpoint to exchange it for an access token.
Method:
POSTEndpoint: Your Token URL (from your client application's metadata).
- Example Base Token URL for a User:
https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token - Example Base Token URL for a Customer:
https://ai.egain.cloud/system/auth/TMPRODB88619984-C/oauth2/token
- Example Base Token URL for a User:
Headers:
| Header | Value |
|---|---|
Content-Type | application/x-www-form-urlencoded |
Body Parameters (application/x-www-form-urlencoded):
| Parameter | Relevance | Description |
|---|---|---|
grant_type | Required | Must be set to authorization_code. |
code | Required | The authorization code you received. |
redirect_uri | Required | The same redirect_uri used in the initial authorization request. |
client_id | Required | The Client ID for your application. |
client_secret | Required | The Client Secret for your application. |
- Example Full Token cURL for a User:
curl --location --request POST 'https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=def456-gh-ijkl-789-mnopqr' \
--data-urlencode 'redirect_uri=https://oauth.pstmn.io/v1/callback' \
--data-urlencode 'client_id=b4b2c1d9-4c19-4e8a-8e7a-9a0b1c2d3e4f' \
--data-urlencode 'client_secret=aBcDeFgHiJkLmNoPqRsTuVwXyZ12345_67890-AbCdEfGh'This flow is required for public clients (SPAs) where a user is present to grant consent but the application cannot securely store a client secret.
The flow has two main parts:
Your application must redirect the user to the eGain authorization endpoint.
Method:
GETEndpoint: Your Authorization URL (from your client application's metadata).
- Example Base Authorization URL for a User:
https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/authorize - Example Base Authorization URL for a Customer:
https://ai.egain.cloud/system/auth/TMPRODB88619984-C/oauth2/authorize
- Example Base Authorization URL for a User:
Query Parameters:
| Parameter | Relevance | Description |
|---|---|---|
client_id | Required | The Client ID for your application. |
response_type | Required | Must be set to code. |
redirect_uri | Required | The URI to redirect to after the user grants or denies permission. |
scope | Required | A space-separated list of scopes. You can include any combination of scopes assigned to your client application in a single request. This allows you to generate one multi-purpose token for your entire application, or separate tokens for specific tasks, depending on your architectural needs. |
state | Recommended | An opaque value used to prevent cross-site request forgery attacks. |
code_challenge | Required | A transform value of the code_verifier used for PKCE. |
code_challenge_method | Required | The method used to generate the code_challenge. Must be S256. |
- Example Full Authorization URL for a User:
https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/authorize?client_id=b4b2c1d9-4c19-4e8a-8e7a-9a0b1c2d3e4f&response_type=code&redirect_uri=https%3A%2F%2Foauth.pstmn.io%2Fv1%2Fcallback&scope=core.aiservices.read%20core.aiservices.write&state=a1b2c3d4e5f67890&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
Once your application receives the authorization code, it exchanges it for an access token.
Method:
POSTEndpoint: Your Token URL (from your client application's metadata).
- Example Base Token URL for a User:
https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token - Example Base Token URL for a Customer:
https://ai.egain.cloud/system/auth/TMPRODB88619984-C/oauth2/token
- Example Base Token URL for a User:
Headers:
| Header | Value |
|---|---|
Content-Type | application/x-www-form-urlencoded |
Body Parameters (application/x-www-form-urlencoded):
| Parameter | Relevance | Description |
|---|---|---|
grant_type | Required | Must be set to authorization_code. |
code | Required | The authorization code received from the previous step. |
redirect_uri | Required | The same redirect_uri used in the initial authorization request. |
client_id | Required | The Client ID for your application. |
code_verifier | Required | The original secret generated by your application before the flow started. |
- Example Full Token cURL for a User:
curl --location --request POST 'https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=def456-gh-ijkl-789-mnopqr' \
--data-urlencode 'redirect_uri=https://oauth.pstmn.io/v1/callback' \
--data-urlencode 'client_id=b4b2c1d9-4c19-4e8a-8e7a-9a0b1c2d3e4f' \
--data-urlencode 'code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'This flow is used for machine-to-machine communication where the application authenticates itself directly without a user present.
This is the standard flow for backend services.
Method:
POSTEndpoint: Your Token URL (from your client application's metadata).
- Example Token URL for a Client App:
https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token
- Example Token URL for a Client App:
Headers:
| Header | Value |
|---|---|
Content-Type | application/x-www-form-urlencoded |
Body Parameters (application/x-www-form-urlencoded):
| Parameter | Relevance | Description |
|---|---|---|
grant_type | Required | Must be set to client_credentials. |
scope | Required | A space-separated list of scopes. You can include any combination of scopes assigned to your client application in a single request. This allows you to generate one multi-purpose token for your entire application, or separate tokens for specific tasks, depending on your architectural needs. |
client_id | Required | The Client ID for your application. |
client_secret | Required | The Client Secret for your application. |
- Example Full Token cURL for a Client App:
curl --location --request POST 'https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=knowledge.portalmgr.manage' \
--data-urlencode 'client_id=b4b2c1d9-4c19-4e8a-8e7a-9a0b1c2d3e4f' \
--data-urlencode 'client_secret=hh2Y0UE8FmaFBBawzMUua1OB8Ks4QWHNUyhDyZj1X7c'This flow is designed for server-side applications that need to perform operations on behalf of a specific user or customer without an interactive login session.
Your application makes a single POST request to the appropriate token endpoint to generate a user-specific access token.
Method:
POSTEndpoint: Your Access Token URL (from your client application's metadata).
- Example Base Access Token URL for Client on behalf of a User
https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token - Example Base Access Token URL for Client on behalf of a Customer
https://ai.egain.cloud/system/auth/TMPRODB88619984-C/oauth2/token
- Example Base Access Token URL for Client on behalf of a User
Headers:
| Header | Value |
|---|---|
Content-Type | application/x-www-form-urlencoded |
Body Parameters (application/x-www-form-urlencoded):
| Parameter | Relevance | Description |
|---|---|---|
grant_type | Required | Must be set to password. |
client_id | Required | The Client ID for your application. |
client_secret | Required | The Client Secret for your application. |
scope | Required | A space-separated list of scopes. You can include any combination of scopes assigned to your client application in a single request. This allows you to generate one multi-purpose token for your entire application, or separate tokens for specific tasks, depending on your architectural needs. |
subject_username | Conditional | The unique username of the user to impersonate. |
subject_userid | Conditional | The unique ID of the user to impersonate. |
subject_email | Conditional | The unique email address of the customer to impersonate. |
User Identification and Best Practices:
- You must provide either
subject_usernameorsubject_useridto identify the user.- You must provide
subject_emailto identify the customer.- It is recommended to use
subject_usernameto ensure optimal performance, as usingsubject_useridcan increase latency.
- Example Full Token cURL for a User:
curl --location --request POST 'https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=7121f585-e403-4531-9a38-1826ebc7e7d8' \
--data-urlencode 'client_secret=*****************' \
--data-urlencode 'scope=knowledge.portalmgr.onbehalfof.read' \
--data-urlencode 'subject_username=pa'This flow allows applications to exchange a valid security token issued by an external Identity Provider (IDP), such as Okta, for an eGain access token. This is ideal for Single Sign-On (SSO) scenarios where you want to leverage existing sessions to call eGain APIs.
- SSO Configuration: The external IDP must be registered and stored in the SSO Provider configuration section of the Administrator Console.
- User Matching: The user identity (e.g., email) contained within the external token's claims must exist in the eGain database.
- Client Enablement: The Client Application must have the "Token Exchange Grant Type" enabled.
- Method:
POST - Endpoint: Your Authorization URL (from your client application's metadata).
- Example Token URL for a Client App:
https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token
- Example Token URL for a Client App:
Headers:
| Header | Value |
|---|---|
Content-Type | application/x-www-form-urlencoded |
Body Parameters (application/x-www-form-urlencoded):
| Parameter | Relevance | Description |
|---|---|---|
grant_type | Required | Must be set to urn:ietf:params:oauth:grant-type:token-exchange. |
subject_token | Required | The valid JWT access token issued by your external IDP (e.g., Okta). |
subject_token_type | Required | The type of token being provided. Use urn:ietf:params:oauth:token-type:access_token. |
registration_id | Required | The unique identifier generated in the Administrator Console for the external IDP registration. |
client_id | Required | The eGain Client ID for your application. |
client_secret | Required | The eGain Client Secret for your application. |
scope | Optional | A space-separated list of eGain scopes requested for the new token. |
Validation Logic: During this request, eGain verifies the token's signature using the external IDP's JWK URL, ensures the iss (issuer) and aud (audience) claims match your registration, and confirms the user exists within eGain.
- Example Token Exchange cURL:
curl --location --request POST 'https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'subject_token=EXTERNAL_IDP_JWT_TOKEN' \
--data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
--data-urlencode 'registration_id=okta_sso_config_01' \
--data-urlencode 'client_id=b4b2c1d9-4c19-4e8a-8e7a-9a0b1c2d3e4f' \
--data-urlencode 'client_secret=aBcDeFgHiJkLmNoPqRsTuVwXyZ12345'Once you have an access token, you can make calls to the eGain APIs by including it in the Authorization header of your request as a Bearer token.
-H "Accept: application/json" \
-H "Authorization: Bearer <your_access_token>"