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.
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: 
[!WARNING] Domain Usage Note: The domain used to request access tokens is
https://ai.egain.cloud/, but the domain for calling the actual APIs ishttps://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.
[!CAUTION] 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.
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'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>"