1. Current Authentication Approach

Today, partners use multiple credential types depending on the integration model, APIs, and operational use case.

The Legacy Workflow

Previously, a partner had to manage split authentication flows:

• Flow A: Client Secret ➔ Generates Partner Token ➔ Generates Partner App Token (Valid only for Bizgate Partner APIs).
• Flow B: Generate App API Key and/or Account-level API Key (Valid only for api.gupshup.io APIs).

The New Unified Workflow

In the new model, the authentication flow is completely unified:

• Client Secret ➔ Generates Universal Token (UT) (Valid for all Bizgate Partner APIs + all api.gupshup.io APIs).

---

Authentication Concepts & Definitions

1.1 Client Secret

A Client Secret is used as part of partner authentication and integration workflows. It is generated individually by any partner admin or non-admin user and must be stored securely.

• New Secrets: Newly regenerated client secrets have a maximum validity of 3 months.
• Legacy Secrets: Existing, never-expiring client secrets remain unchanged for now (updates to this behavior are planned for future security enhancements).
• Expiry Reminders: Currently on the product roadmap.

1.2 Partner Token

Used to generate/retrieve a Partner App Token or to fetch all partner apps within onboarding APIs.

• Generation: Created using a user's Client Secret.
• Deprecation Notice: The legacy method of creating a partner token using just the Bizgate Partner Portal password is now deprecated.
• TTL / Expiry: 24 hours.

1.3 Partner App Token (PAT)

Used for partner-level API authentication specifically for the https://partner.gupshup.io/ endpoint.

• Constraints: Only one PAT can exist at any given time.
• Generation: Can be generated by both admin and non-admin users via the Bizgate Partner Portal UI or API.
• TTL / Expiry: Long-lived.
• Scope: Works at the app level for all apps linked to the partner.

1.4 Account API Key

Provides authentication at the Gupshup account level (including app level) and is commonly used across https://api.gupshup.io/ endpoints.

• Scope: Not restricted to a single app; has global scope for a given Customer ID. Used to authenticate any apps present in a given Customer ID, whether linked to a partner or not.
• TTL / Expiry: Long-lived.
• Availability Note: No longer exposed or passed on to new Customer IDs since March 2026.

1.5 App API Key

Generated at the application level and scoped to a specific app. Commonly used across https://api.gupshup.io/ endpoints.

• Constraints: A maximum of 2 active app-level API keys per app can exist concurrently.
• Scope: Strictly restricted to a single app (authenticates the app whether it is linked to a partner or not).
• TTL / Expiry: Long-lived.

---

2. New Authentication Method

The future authentication model streamlines access control around a simplified set of credentials while phasing out legacy types.

Universal Tokens (UT)

Universal Tokens (UT) provide a unified, secure, and simplified authentication mechanism for partner-linked applications. By adopting Universal Tokens, you eliminate the overhead of managing multiple split API keys, reducing security risks and streamlining integration management.
NOTE : It does not work apps not linked to your partner ID.

Key Characteristics

• Unified Access: Works seamlessly across all apps linked to a partner. Validates requests for both https://api.gupshup.io/ and https://partner.gupshup.io/ across all API endpoints.
• Admin-Controlled: Only administrators can generate or revoke UTs via the UI (API management is planned). Automated email alerts are triggered to notify admins of any generation or revocation activities.
• Token Limits: A maximum of 3 active Universal Tokens are allowed at any one time per partner. It means that when you want to rotate the first universal token, you can create a second UT while the first UT keeps running. Once you have made your integration changes with the second UT, you can retire the first UT.
• Flexible Expiry: Configurable validity between a minimum of 24 hours and a maximum of 60 days. Partners are responsible for rotating tokens prior to expiration.
• Non-Disruptive Migration: UTs work concurrently alongside legacy App tokens and API keys. Once you have successfully verified your UT integration, you can disable legacy mechanisms to minimize security exposure without breaking active operations.

---

Steps to Generate a Universal Token

Prerequisites

• Your user account must have Admin access on the Gupshup Bizgate Partner Portal.
• The Universal Token configuration section becomes available only after completing the initial Security Wizard steps up to the 'Client Secret' phase. See the Bizgate Partner Portal Security Wizard Guide for details.
• Universal token works only for apps linked to your partner ID.

Generation Workflow

The generation and consumption of a Universal Token is completely non-disruptive to active live operations.

1. Navigate to the Settings section in the Bizgate Partner Portal.
2. Open the Universal Token Management section.
3. Click on Generate Universal Token.
4. Configure your preferred token expiry duration (between 24 hours and 60 days).
5. Confirm token generation.
6. Copy and securely store the generated token immediately.

UI Walkthrough

1. Locate the Universal Token panel in your account configuration:

2. Set the token name and expiry window:

3. View and safely copy the token:

4. Revoke a token instantly if it is compromised or no longer needed:

5. Confirm access revocation:

Automated System Notifications

Whenever a token action occurs, administrators will receive automated confirmation emails:

• Creation Alert:

  

• Revocation Alert:

  

---

---

Disabling Legacy Authentication Mechanisms

After establishing and validating your Universal Token integration, you should systematically deprecate old credentials. If unexpected downtime or issues occur, the portal allows you to Undo the deprecation instantly to restore legacy traffic.

Recommended Migration Approach

Phase 1 – Parallel Usage

Partners may initially:

• Continue using existing API keys and tokens
• Validate all workflows using UT
• Ensure operational stability

Phase 2 – Controlled Migration

Once UT usage is validated:

• Disable Account API Keys
• Disable App API Keys
• Disable Partner App Tokens

Steps to Disable Legacy Keys

Navigate to your Universal Token Security Settings panel to manage toggles for legacy formats:

Deactivating Account API Keys

1. Toggle off Account-level authorization:

2. Confirm deactivation:

3. Optional: if rollback is required click Reactivate Gupshup account API keys

Deactivating App Level API Keys

1. Click Deactivate App level API keys

Deactivating Partner App Tokens (PAT)

1. Turn off the primary legacy Partner App Token toggle:

2. Confirm system impact:

---

Conclusion

Migrating to Universal Tokens yields a significantly safer, unified, and transparent authentication lifecycle. Once legacy parameters are successfully disabled by a platform admin via the Bizgate Partner Portal, older credentials will immediately fail authentication requests across all partner-linked applications, preventing unauthorized external access.