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

div
iframe
script
### 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 → `Partition` → `Integration` → `Client Application` then click the **(+) Plus** button to create a new application..
![Create Client Application](/assets/create_client_application.9040ff4bbacb6d879fc3fce4b37a557c3bfbfa81367e3d5a9106c726e6d94059.afe294b5.png)
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. 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 App Details Form](/assets/client_app_details_form.334733dfae885f11659000a32cc9bf4d0dbf293335b150766f00cdae5b43cde4.afe294b5.png)
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](/assets/client_secret.e890bc61c9f03b8acb9be3732d63a0d29b71fe937ae87a299708f28e2f1aff00.afe294b5.png)
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**: 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.
  * **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/`.
![Client App Permissions](/assets/client_app_permissions.d53acc94717841a37d6065f3a8250f7da4bbba04a13515a92a25ce987a2af68d.afe294b5.png)
> **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.


## 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](/assets/client_metadata.d34e7086743eadde3ced3d9062ab0f84636a73bafa398e300e50e619a833eba3.afe294b5.png)

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:**
![Metadata Details](/assets/client_metadata_details.a92f1b30682307cbace821a4d60311a6cd42df8d0c266363e4af8b9153e80924.afe294b5.png)

> [!WARNING]
**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.


## Step 3: Choose the Right Authentication Flow

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


## Authentication Flow Implementations

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.



### 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:**

```
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
```


**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
```


#### **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:**

```
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
```


**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
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'
```

### Authorization Code Flow with PKCE (for SPAs)

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:

#### **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:**

```
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
```


**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
```


#### **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:**

```
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
```


**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
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'
```

### Client Credentials Flow (for Server-to-Server)

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:**

```
https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token
```


**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
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'
```

### On-Behalf-Of Flow

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.

#### **Generate an On-Behalf-Of Access Token**

Your application makes a single `POST` request to the appropriate token endpoint to generate a user-specific access token.

* **Method**: `POST`
* **Endpoint**: 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
```


**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_username` or `subject_userid` to identify the user.
* You must provide `subject_email` to identify the customer.
* It is **recommended to use `subject_username`** to ensure optimal performance, as using `subject_userid` can increase latency.



* **Example Full Token cURL for a User:**



```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=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'
```

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


```bash
-H "Accept: application/json" \
-H "Authorization: Bearer <your_access_token>"
```