---
updatedAt: 2026-11-06T18:07:44.000Z
agentTools:
  projectIndex: https://partner-docs.gupshup.io/llms.txt
---

# Linking Gupshup.ai apps with Partner

Gupshup.ai App Linking & Partner Linking

<Callout icon="📘" theme="info">
  ### Effective dates:

  16 September 2026: New security controls and new linking methods become available. These are backward compatible and existing methods will continue to work.<br />5th November 2026: Existing App ID + App-level API Key app linking methods is deprecated.
</Callout>

## This guide explains the existing and new ways to link customer apps with Gupshup partners, the security controls available to partners, the new token-based linking methods, authentication requirements, and the migration path from legacy linking methods.

***

##

***

# 1. Overview

Gupshup.ai is introducing more secure mechanisms for linking customer apps with partners, along with additional security controls for existing partner-linking methods.

### Key changes

1. **Partner ID-based linking continues for existing use cases**, but partners can:
   * Disable automatic approval of linking requests.
   * Completely disable Partner ID-based linking.

2. **As of&#x20;**&#x35;th November 2026: Existing App ID + App-level API Key app linking methods is deprecated.

3. Two new, more secure linking mechanisms are available:
   * **Partner Linking Token**
   * **App Linking Token**

4. New linking APIs support:
   * **Partner Tokens**
   * **Universal Tokens**

5. New linking methods **do not support** Gupshup.ai account-level or app-level API keys/tokens.

6. **Customer App Tokens and Account Secrets** in self-serve apply only to apps that are not linked to a partner. Once an app is linked to a partner, generation of new Customer App Tokens will not be allowed.

***

# 2. What Is Changing

The overall direction is to move partner linking away from:

* Shared application credentials
* Automatically trusted Partner IDs
* Manual credential sharing

and toward:

* Partner-controlled approval
* Token-based linking
* Partner-side validation
* Partner Tokens / Universal Tokens for API authentication

### Recommended direction

```text
Customer creates app
        ↓
Secure linking token
        ↓
Linking request
        ↓
Partner validation
        ↓
Approve / Reject
```

***

# 3. Existing Linking Methods

## 3.1 Partner ID-Based Linking

### Current flow

A customer can create an app on Gupshup.ai and enter a partner's Partner ID to initiate linking.

Historically, the request was automatically approved and the app became linked to the partner.

### Security Control 1 — Disable Auto-Approval

**Recommended for all partners.**

Partners can turn off automatic approval of Partner ID requests.

Go to:

```text
Partner Portal
→ Settings
→ App Linking
→ Disable "Auto-approve Partner ID requests"
```

![](https://files.readme.io/37fb7ea7353e0dfbd409f720d7d563402312ed1dc40b273cd613b4f1d90e013e-7dee263e-c82f-4f84-8ce3-c0d315252211.png)

### After auto-approval is disabled

1. The customer initiates linking using the Partner ID.
2. A linking request is created.
3. The partner receives the request. (check <Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/listapplinkrequests">API docs</Anchor>)
4. The partner can **Approve** or **Reject** the request. (check <Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/decideapplinkrequest">docs</Anchor>)
5. Approval/rejection can be done:
   * Through the Partner Portal UI (by any user)
   * Through the available APIs

Requests are also available under:

```text
Apps
→ App linking requests
```

![](https://files.readme.io/6d499766cdb7f34552987dc2e042a98126a66a706ba536483edcee2502bad97a-Screenshot_2026-09-16_120652.png)

### API authentication

The request APIs can be authenticated using:

* Partner Tokens
* Universal Tokens

Users on gupshup.ai - on clicking ‘Add partner ID’ will now see 2 options as below. To continue with the old process they must select ‘Link using partner ID’

![](https://files.readme.io/d5f909f86103bb1219fa0a230a3d510b44aea49d62871078663b08c7ec4417a4-ChatGPT_Image_Sep_16_2026_12_10_39_PM.png)

<br />

***

## Security Control 2 — Disable Partner ID Linking Completely

**Recommended for partners who do not have apps on Gupshup.ai and want to move completely to token-based linking.**

Go to:

```text
Partner Portal
→ Settings
→ App Linking
→ Disable "Allow linking with partner ID"
```

![](https://files.readme.io/c6c0a253bbd5383193aae74a470ae0e401f11538f3e67e1248288d0ded7b3936-7dee263e-c82f-4f84-8ce3-c0d315252211.png)

When this is disabled, customers cannot use the Partner ID mechanism to establish a link.
Gupshup.ai user will see the below error if you disable the toggle.

![](https://files.readme.io/ffe58c4b78572f595959f2d67267a46c5221914e68bfe1b3dae0124bdfd1e75d-Screenshot_2026-09-16_121523.png)

### Recommended direction

Use one of the secure token-based methods instead:

* Partner Linking Token
* App Linking Token

***

## 3.2 App ID + Account-Level API Key

### Old flow (deprecated as of 5th Nov 2026)

The legacy flow requires the partner to have:

* App ID
* Account-level API Key

The customer shares these application credentials with the partner.

### Why this is deprecated

The source guide identifies the following security concerns:

* Customers have to share their App ID and API credentials.
* There is no two-sided authentication of the app owner.

### Deprecation

**As of&#x20;**&#x35;th November 2026: Existing App ID + App-level API Key app linking methods is deprecated.

Partners using this method should migrate to a secure token-based mechanism.

***

# 4. New Linking Methods

There are two new secure linking mechanisms:

1. **Partner Linking Token**
2. **App Linking Token**

***

# 4.1 Partner Linking Token

## What is it?

Instead of sharing a simple Partner ID, a partner can generate a **Partner Linking Token**.

The token is:

* A complex alphanumeric value
* Valid for **30 days**
* Regeneratable after expiry
* Supported through APIs for regeneration

> Note that a provision for secondary tokens to work in parallel with primary tokens is under development.

### Where to generate it

a. Through APIs <br /><Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/getorregeneratelinkingtoken">API to generate or regenerate Partner Linking token</Anchor>

<Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/getlinkingtoken">API to get Partner Linking token details</Anchor>

<br />

b. Through the Portal

```text
Partner Portal
→ Settings
→ App Linking
→ Partner Linking Token
```

![](https://files.readme.io/bb85d37d346ca4122d99a372775f9c2dc7fff56eb5d91a31ca4aeadd909d6d0e-Screenshot_2026-09-16_122700.png)

Partners can generate a new token every 30 days and include it in their customer onboarding documentation.

***

## Customer flow

1. Customer goes to **Gupshup.ai**.
2. Customer opens the **Link a Partner** flow.
3. Customer chooses:
   * Link with Partner ID
   * Link with Partner Token
4. Customer selects **Link with Partner Token**.
5. Customer enters the Partner Linking Token provided by the partner.
6. Customer submits the linking request.

![](https://files.readme.io/9d5145cf145d21899310ab3224f73fcf9e3633d488ba4908d3bc60fdf85ef702-ChatGPT_Image_Sep_16_2026_12_31_31_PM.png)

***

## Partner flow

The partner receives the linking request and can:

* View the request in the Partner Portal
* Pull the request through APIs (check <Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/listapplinkrequests">docs)</Anchor>
* Approve the request (check <Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/decideapplinkrequest">docs</Anchor>) (by any user)
* Reject the request

Requests are also available under:

```text
Apps
→ App linking requests
```

The APIs support:

* Partner Tokens
* Universal Tokens

![](https://files.readme.io/04e1724f19a8eb225886ad6655e2f40c55dbb9d05ae3dffdef287dd3f19de26c-Screenshot_2026-09-16_120652.png)

***

## Request identifiers

The linking request provides identifiers such as:

* Customer ID
* User email
* Username

Partners can use these identifiers for internal validation before approving the request.

### Example validation

A partner can verify that the **Customer ID belongs to an existing customer in its own system** before approving the linking request.

***

## Recommended use case

Use **Partner Linking Token** when:

* Customers create their own apps on Gupshup.ai.
* Those customers need to link the apps to a partner.
* The partner wants a more secure replacement for Partner ID-based linking.

> **Recommended replacement:** Partner Linking Token should be the preferred replacement for Partner ID-based linking for new customer onboarding.

***

# 4.2 App Linking Token

## What is it?

The App Linking Token is designed for cases where the customer should not share:

* App ID
* API Key
* Account credentials

with the partner.

***

## Customer flow

1. Customer goes to **Gupshup.ai**.
2. Customer generates an **App Linking Token**.
3. Customer shares the token with the partner.

***

## Partner flow

The partner receives the App Linking Token and uses the available API with:

* App Linking Token
* Partner authentication

The app is then linked to the partner.

Read <Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/linkappbysstoken">API docs</Anchor>

***

## Key advantage

The customer does **not** need to share:

* App ID
* Account-level API Key

with the partner.

This provides a more secure way for the customer to initiate linking without exposing application credentials.

***

## Recommended use case

Use **App Linking Token** when:

* Customers currently create apps on Gupshup.ai.
* Customers currently share App ID/API Key with the partner.
* The existing credential-sharing flow needs to be migrated.

The source guide recommends migrating those customers from the legacy **App ID + API Key** flow to the **App Linking Token** flow.

***

# 5. Authentication for New APIs

All new linking APIs support:

* **Partner Tokens**
* **Universal Tokens**

They do **not** support:

* Account-level API Keys
* App-level API Keys
* App-level API tokens

### Recommendation

Ensure all integrations using the new linking APIs are authenticated with the appropriate:

```text
Partner Token
        OR
Universal Token
```

***

# 6. Partner-Specific Recommendations

## Scenario A — Partner creates and manages its own apps

If the partner uses Gupshup.ai to create an app and then links it to its Partner ID:

### Recommended actions

1. Disable automatic approval for Partner ID linking.
2. Integrate the request-polling APIs (check <Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/listapplinkrequests">docs</Anchor>) or monitor the Partner Portal.&#x20;
3. Validate the Customer ID against the partner's own systems.
4. Approve only requests belonging to the expected customer base. (check <Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/decideapplinkrequest">docs</Anchor>) (by any user)

This keeps the existing Partner ID workflow while adding partner-side validation.

***

## Scenario B — Partner currently uses app linking APIs

The existing onboarding API-based approach is deprecated by **5th Nov 2026**

The recommended target flow is:

```text
Customer / App Creation
        ↓
Partner Linking Request
        ↓
Partner Validation
        ↓
Partner Approval
```

<br />

***

## Scenario C — Customers create apps and link using Partner ID

For customers creating apps on Gupshup.ai and linking them with a Partner ID:

### Do not rely on automatic approval.

Partners should:

1. Disable auto-approval.
2. Validate incoming requests.
3. Move new implementations to Partner Linking Token through APIs or the Portal.

   <Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/getorregeneratelinkingtoken">API to generate or regenerate Partner Linking token</Anchor>

   <Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/getlinkingtoken">API to get Partner Linking token details</Anchor>

### Recommended flow

```text
Customer
   ↓
Partner Linking Token
   ↓
Linking Request
   ↓
Partner Validation
   ↓
Approve / Reject
```

***

## Scenario D — Customers used to share App ID + API Key

### Legacy flow

```text
Customer
   ↓
App ID + API Key
   ↓
Partner
   ↓
App Linked
```

### Recommended flow

```text
Customer
   ↓
App Linking Token
   ↓
Partner API
   ↓
App Linked
```

Customers no longer need to share their App ID or API key with the partner.

Read <Anchor target="_blank" href="https://partner-docs.gupshup.io/reference/linkappbysstoken">API docs</Anchor>

***

# 7. Customer App Token & Account Secret Changes

Customer App Tokens and Account Secrets in self-serve apply only to apps that are **not linked to a partner**.

Once an app is linked to a partner:

* Existing applicable controls continue according to platform rules.
* Generation of a **new Customer App Token is not allowed**.

Therefore, customers who intend to work through a partner should use the partner-linking mechanisms instead of relying on Customer App Tokens or Account Secrets.

***

#

# 8. Quick Decision Guide

| Partner situation                               | Recommended approach                                                         |
| ----------------------------------------------- | ---------------------------------------------------------------------------- |
| Partner creates its own apps on Gupshup.ai      | Partner ID linking with auto-approval disabled + request validation          |
| Customers create apps and link using Partner ID | Migrate to Partner Linking Token                                             |
| Customers share App ID + API Key                | Migrate to App Linking Token                                                 |
| Default recommended behaviour                   | Disable auto-approval and use request APIs / Portal                          |
| Partner does not want Partner ID linking        | Disable Partner ID linking and use Partner Linking Token / App Linking Token |
| Partner needs customers to share credentials    | Avoid credential sharing; use App Linking Token                              |