API Authentication

Introduction

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.

Understanding OAuth 2.0

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.

Step 1: Create a Client Application

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.

To Create a Client Application:

  1. Log in to your Administrator Console with a Partition Administrator (PA) account.
  2. Navigate to the Client Application creation screen by going to Department dropdown and selecting Partition then by going to → Integration → Client Application then Create Client Application with the Yellow Plus Button. Create Client Application
  3. 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. For self-service environments, the only option available is Global.
      • Global
      • User
      • Customer
    • 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.
      • Public Client/Native : Select this for applications running on end-user devices, like mobile or desktop apps. Similar to SPAs, these are public clients.

        Note: This option is only available for Commercial environments.

      The table below outlines key differences between these platform types:

      Feature Public Clients (Native & SPAs) 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, SPAs 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. This is a critical part of the OAuth 2.0 flow.

    Client App Details Form

  4. 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.

    Client Secret

  5. 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 are used when your application is acting on behalf of a user.
    • Application permissions are used when your application is acting on its own behalf (server-to-server).

    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/.

    Client App Permissions

Step 2: Find Your API Endpoints (Metadata)

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.

Metadata

This will provide you with the following crucial values:

  • Authorization URL : The endpoint to redirect users to for authorization.

    Note: Commercial environment utilizes domain_hint query parameter to identify the environment within the common authorization URL, this will automatically be added at the end of the authroization URL in Metadata.

  • Token URL : The endpoint to exchange an authorization code for an access token or to use the client credentials flow.
  • Scope Prefix : The prefix required for your defined scopes. If this does not show up in your Metadata, then it will just be the scope names (i.e, core.aiservices.manage).

    For a Commercial Environment use the below prefix if scope prefix field is not present in Metadata:

    Copy
    Copied
       api.ai.egain.cloud/auth/
  • 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 for a self-service environment: Metadata Details

Step 3: Choose the Right Authentication Flow

Authentication is handled based on four 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 .
  • Anonymous Customer : An end-user who is not logged in. This persona uses the Client Credentials flow .
  • Client App : The application itself, acting on its own behalf for server-to-server integrations. This persona uses the Client Credentials flow .

Authentication Flow Implementations

The following sections provide detailed instructions for implementing each of the supported OAuth 2.0 flows.

Authorization Code Flow (for Web Applications)

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:

Part 1: Request User Authorization

Your application needs to redirect the user to the eGain authorization endpoint to get their permission.

  • Method : GET
  • Endpoint : Your Authorization URL (from your client application's metadata).
    • Example Base Authorization URL for a User on a Commercial Environment:
      Copy
      Copied
      https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_User_V3_SignIn_OIDC/oauth2/v2.0/authorize?domain_hint=developerv3api.egain.cloud
    • Example Base Authorization URL for a User on a Self Service Environment:
      Copy
      Copied
      https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/authorize
    • Example Base Authorization URL for a Customer on a Commercial Environment:
      Copy
      Copied
      https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_Customer_V3_SignUpOrSignIn_OIDC/oauth2/v2.0/authorize?domain_hint=developerv3api.egain.cloud
    • Example Base Authorization URL for a Customer on a Self Service Environment:
      Copy
      Copied
      https://ai.egain.cloud/system/auth/TMPRODB88619984-C/oauth2/authorize

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 delegated permissions your application is requesting.
state Recommended An opaque value used to prevent cross-site request forgery attacks.
  • Example Full Authorization URL for a User on a Commercial Environment: https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_User_V3_SignIn_OIDC/oauth2/v2.0/authorize?domain_hint=developerv3api.egain.cloud&client_id=b4b2c1d9-4c19-4e8a-8e7a-9a0b1c2d3e4f&response_type=code&redirect_uri=https%3A%2F%2Foauth.pstmn.io%2Fv1%2Fcallback&scope=https%3A%2F%2Fapi.egain.cloud%2Fauth%2Fcore.aiservices.manage&state=a1b2c3d4e5f67890

Part 2: Exchange Authorization Code for an Access Token

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 : POST
  • Endpoint : Your Token URL (from your client application's metadata).
    • Example Base Token URL for a User on a Commercial Environment:
      Copy
      Copied
      https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_User_V3_SignIn_OIDC/oauth2/v2.0/token
    • Example Base Token URL for a User on a Self Service Environment:
      Copy
      Copied
      https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token
    • Example Base Token URL for a Customer on a Commercial Environment:
      Copy
      Copied
      https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_Customer_V3_SignUpOrSignIn_OIDC/oauth2/v2.0/token
    • Example Base Token URL for a Customer on a Self Service Environment:
      Copy
      Copied
      https://ai.egain.cloud/system/auth/TMPRODB88619984-C/oauth2/token

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 on a Commercial Environment:
    Copy
    Copied
    curl --location --request POST 'https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_User_V3_SignIn_OIDC/oauth2/v2.0/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'

Authorization Code Flow with PKCE (for SPAs and Native Apps)

This flow is required for public clients (SPAs, native mobile apps) where a user is present to grant consent but the application cannot securely store a client secret.

The flow has two main parts:

Part 1: Request User Authorization

Your application must redirect the user to the eGain authorization endpoint.

  • Method : GET
  • Endpoint : Your Authorization URL (from your client application's metadata).
    • Example Base Authorization URL for a User on a Commercial Environment:
      Copy
      Copied
      https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_User_V3_SignIn_OIDC/oauth2/v2.0/authorize?domain_hint=developerv3api.egain.cloud
    • Example Base Authorization URL for a User on a Self Service Environment:
      Copy
      Copied
      https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/authorize
    • Example Base Authorization URL for a Customer on a Commercial Environment:
      Copy
      Copied
      https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_Customer_V3_SignUpOrSignIn_OIDC/oauth2/v2.0/authorize?domain_hint=developerv3api.egain.cloud
    • Example Base Authorization URL for a Customer on a Self Service Environment:
      Copy
      Copied
      https://ai.egain.cloud/system/auth/TMPRODB88619984-C/oauth2/authorize

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 delegated permissions your application is requesting.
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 on a Commercial Environment: https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_User_V3_SignIn_OIDC/oauth2/v2.0/authorize?domain_hint=developerv3api.egain.cloud&client_id=b4b2c1d9-4c19-4e8a-8e7a-9a0b1c2d3e4f&response_type=code&redirect_uri=https%3A%2F%2Foauth.pstmn.io%2Fv1%2Fcallback&scope=https%3A%2F%2Fapi.egain.cloud%2Fauth%2Fcore.aiservices.read%20https%3A%2F%2Fapi.egain.cloud%2Fauth%2Fcore.aiservices.write&state=a1b2c3d4e5f67890&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

Part 2: Exchange Authorization Code for an Access Token

Once your application receives the authorization code, it exchanges it for an access token.

  • Method : POST
  • Endpoint : Your Token URL (from your client application's metadata).
    • Example Base Token URL for a User on a Commercial Environment:
      Copy
      Copied
      https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_User_V3_SignIn_OIDC/oauth2/v2.0/token
    • Example Base Token URL for a User on a Self Service Environment:
      Copy
      Copied
      https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token
    • Example Base Token URL for a Customer on a Commercial Environment:
      Copy
      Copied
      https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_Customer_V3_SignUpOrSignIn_OIDC/oauth2/v2.0/token
    • Example Base Token URL for a Customer on a Self Service Environment:
      Copy
      Copied
      https://ai.egain.cloud/system/auth/TMPRODB88619984-C/oauth2/token

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 on a Commercial Environment:
    Copy
    Copied
    curl --location --request POST 'https://login.egain.cloud/f51302dd-7036-41b5-b619-e1a52a67c780/B2C_1A_User_V3_SignIn_OIDC/oauth2/v2.0/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'

Client Credentials Flow (for Server-to-Server and Anonymous Users)

This flow is used for machine-to-machine communication where the application authenticates itself directly without a user present.

For a Client App (Server-to-Server)

This is the standard flow for backend services.

  • Method : POST
  • Endpoint : Your Token URL (from your client application's metadata).
    • Example Token URL for a Client App on a Commercial Environment:
      Copy
      Copied
      https://login.egain.cloud/global/f51302dd-7036-41b5-b619-e1a52a67c780/oauth2/v2.0/token
    • Example Token URL for a Client App on a Self Service Environment:
      Copy
      Copied
      https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token

Headers:

Header Value
Content-Type application/x-www-form-urlencoded
Authorization Basic <base64-encoded-client_id:client_secret>

Body Parameters (application/x-www-form-urlencoded):

Parameter Relevance Description
grant_type Required Must be set to client_credentials.
scope Required For this flow, you must use the special scope https://api.egain.cloud/auth/.default.
  • Example Full Token cURL for a Client App on a Commercial Environment:
    Copy
    Copied
    curl --location --request POST 'https://login.egain.cloud/global/f51302dd-7036-41b5-b619-e1a52a67c780/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ZDFlOGMyYjUtM2ExOC00ZjdiLTljNmQtOGU1ZjdhNGIzYzJkOnhZejFBYkMyZEVmM0doSTRqS2w1TW5QNnFSczdUdlc4eFl6X0FiQ2RFZkdo' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=https://api.egain.cloud/auth/.default'

For an Anonymous Customer

This flow is a specific implementation of client credentials to get a token for an anonymous user.

  • Method : POST
  • Endpoint : The specific Token URL for anonymous customers (from the metadata).
    • Example Token URL for an Anonymous Customer:
      Copy
      Copied
      https://login.egain.cloud/internal/oauth2/v2.0/anonymous/token?user_type=customer&domain_hint=api.egain.cloud

Body Parameters (application/x-www-form-urlencoded):

Parameter Relevance Description
grant_type Required Must be set to client_credentials.
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 application permissions required for anonymous access.
  • Example Full Token cURL for a Client App on a Commercial Environment:
    Copy
    Copied
    curl --location --request POST 'https://login.egain.cloud/internal/oauth2/v2.0/anonymous/token?user_type=customer&domain_hint=api.egain.cloud' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=d1e8c2b5-3a18-4f7b-9c6d-8e5f7a4b3c2d' \
--data-urlencode 'client_secret=xYz1AbC2dEf3GhI4jKl5MnP6qRs7TvW8xYz_AbCdEfGh' \
--data-urlencode 'scope=https://api.egain.cloud/auth/core.aiservices.read https://api.egain.cloud/auth/core.aiservices.manage'

Step 4: Making Authenticated API Requests

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.

Copy
Copied
-H "Accept: application/json" \
-H "Authorization: Bearer <your_access_token>"