Scenarios
The consumer key is the core credential for client applications to securely call the AI Gateway service. When enterprises or developers integrate and orchestrate backend AI capabilities through the microservices TSF AI Gateway, unique identity authentication credentials are created by the consumer key for different clients (such as business applications, mobile apps, or third-party services). These credentials are used for identity authentication and access control when these clients call the gateway API.
To ensure the security of sensitive key information, the microservice TSF AI Gateway is deeply integrated with Tencent Cloud Key Management System (KMS), enabling encrypted storage of keys throughout their entire lifecycle. KMS uses third-party certified Hardware Security Modules (HSMs) to generate and protect keys. This ensures that no one, including Tencent Cloud, can obtain your plaintext master keys, meeting stringent compliance requirements. Through centralized management, this feature aims to enhance security controls, eliminate the risks of plaintext leakage and unauthorized access, and simplify Ops processes such as key creation, update, disablement, and deletion.
After creating a key and binding it to a consumer (a single consumer can be bound to multiple types of keys, and a single key can be bound to at most one consumer), you must also configure the corresponding authentication policy on the model API or MCP service to complete the full access control chain.
This document guides you on how to create a key (authentication credential) for a consumer in the AI Gateway.
Prerequisites
If the KMS credential is used as the generation method, you need to create a credential. For details, see SSM - Quick Start. Operation Steps
Viewing Keys
2. On the instance list page, click the ID of the gateway instance you want to configure to go to its basic information page.
3. In the left sidebar, click Key Management to go to the key list page.
4. At the top of the page, click the Consumer Key tab.
5. The list page displays all created consumer keys, including information such as key name, type, status, and generation method. You can create, edit, or delete keys here.
6. When the key status is "Enabled", the delete operation is grayed out and unavailable. The system prompts you with "Please disable the key first".
Creating a Key
1. On the Consumer Key list page, click New.
2. In the Create Key window, configure the following common basic parameters for the key:
|
Key Name | Yes | 2-60 characters. Supports uppercase and lowercase letters in Chinese and English, digits, and separators ("-", "_"). Cannot start with a digit or separator. Cannot end with a separator. |
Credential Type | Yes | Select a credential type: API Key / JWT / OAuth 2.0 / OIDC. Configuration items vary for different types. For details, see the next step. API Key is the simplest authentication method, suitable for internal services or trusted clients. JWT (JSON Web Token) is suitable for scenarios that require transmitting user identity information. The client issues the Token itself and carries it in requests. OAuth 2.0 is suitable for scenarios that require integrating with third-party OAuth services. In these scenarios, the client uses a Client ID/Secret to obtain a Token and then carries it for access. OIDC (OpenID Connect) is an identity authentication protocol based on OAuth 2.0, suitable for scenarios that require user identity authentication. |
Description | No | The identification description information for the key. Up to 200 characters can be entered. |
3. Enter the specific credential configuration parameters.
3.1 Credential Type: API Key
|
Generation Method | Yes | Custom: Manually enter the key value (the consumer key serves as the credential content). |
|
| Key Management Service (KMS Credential): Associates with the credential in Tencent Cloud KMS. Enter the "Credential Name" and "Credential Version". If no KMS credential exists, click "New Credential" to navigate and create one. |
|
| Auto-generated: The gateway automatically generates a random API key. |
Credential Content | Yes | 8-60 characters. Supports uppercase and lowercase English letters, digits, and symbols ("-", "_", "="). The characters "-" and "_" cannot be used as the first or last character. |
Note:
Once an API Key is generated, keep it secure and do not disclose it to unauthorized personnel.
3.2 Credential Type: JWT
|
Algorithm | Yes | Select a JWT signing algorithm, such as HS256. |
Shared Secret | Yes | Enter the shared secret used for signing and verifying JWT. |
Consumer Identifier | Yes | When a client self-signs a JWT, set the iss claim to this value. The gateway uses this value to look up the corresponding consumer. Use a business-readable name, such as an organization name / email address. |
3.3 Credential Type: OAuth 2.0
|
Client ID | Yes | OAuth client ID. |
Client secret | Yes | OAuth client secret. |
3.4 Credential Type: OIDC
|
Client ID | Yes | OIDC client ID. |
Client secret | Yes | OIDC client secret. |
Issuer URL | Yes | Issuer URL of the identity provider (IdP), used to discover OIDC configurations, such as https://example.com/oidc. |
Consumer Identifier Claim Value | Yes | The claim value of the user in the IdP token, such as sub/email, is used at runtime to look up the corresponding consumer, for example, user@example.com. |
4. Complete the creation: Click OK to finish creating the key. The newly created key will be displayed in the consumer key list.
Key Binding to Consumers
Consumers and keys have a one-to-many relationship. A consumer can be bound to multiple keys, but a key can be bound to only one consumer. You can bind a consumer to a key.
1. On the Consumer Key List page, click the ID/Name of the target key to go to the details page.
2. Click Add Resource. In the Add Resource dialog box, all available consumers are listed in the left-side "Select Consumers" area. You can use the search box to quickly find them.
3. In the list on the left, select a consumer to bind to this key. The selected consumer will appear in the "Selected" list on the right.
4. To remove a consumer, click the × icon to the right of a consumer entry in the "Selected" list on the right. This removes it from the current association group. Alternatively, you can directly select a new consumer.
5. After making the adjustments, click OK to save the association.
Viewing Key Details
1. On the Consumer Key List page, click the ID/Name of the target key.
2. Go to the key details page. You can view the following information:
Basic Information: Includes the key ID, name, type, status, creation time, and so on.
Bound Consumers: Displays information about the consumers that are associated with the current key.
Editing a Key
1. On the Consumer Key List page, locate the target key and click Edit in its operation column. Alternatively, on the key details page, click Edit in the upper-right corner.
2. In the edit window, you can modify the key's name and description (remarks).
3. Click OK to save the modifications.
Note:
An API Key credential cannot be modified after creation. If you need to replace it, delete the existing key and create a new one.
Enabling/Disabling the Key
A consumer key takes effect only when it is enabled. This means that when a key is disabled or inactive, the AI Gateway cannot recognize or use it for any operations. Therefore, before using a key, you must confirm whether it has been correctly enabled.
1. On the Consumer Key List page, locate the target key and click the Disable button in its operation column. The key will then be in the "Disabled" state, and the AI Gateway will be unable to recognize or use it for any operations.
2. To perform the enable operation, the target key must be in the "Disabled" state. Click Enable. The key will then be in the "Enabled" state.
Deleting the Key
1. On the Consumer Key List page, locate the target key and click the Disable button in its operation column. You can delete the key only after it is disabled. After the key is disabled, click Delete.
2. A dependency check will be performed before deletion:
If the key has been disassociated from all resources (for a consumer key, it must be disassociated from all consumers), a dialog box will directly display the key information. Click OK to delete it.
If the key still has associated resources, a dialog box will prompt "There are unresolved dependencies" and list the specific dependencies. You must first remove all dependencies, then click Recheck. You can delete the key only after the check passes.
Note:
Deleting a key is an irreversible operation. Proceed with caution.
KMS Credential Status Change: If you modify a credential in the Tencent Cloud KMS console, the AI Gateway will briefly continue using the cached old credential content (the default cache duration is about 5 minutes) to ensure business continuity. We recommend that you create a new version of the credential in KMS, associate the new credential in the gateway, and then delete the old API Key version to ensure the change takes effect promptly.
To enhance the high availability of keys, we recommend that you configure multiple credentials. This prevents service unavailability for consumers and potential incidents if a credential is disabled.
Credential Security: Credential information, such as API Keys, shared secrets, and client secrets, must be securely stored. Do not commit them to code repositories or public channels.
Credential Rotation: We recommend that you rotate credentials periodically to reduce the risk of credential exposure.
Subsequent Operations
After a consumer key is created, you must configure an authentication policy on the model API or MCP service to declare the authentication methods and validation rules accepted by the service. For details, see:
Synchronizing Consumer Keys to Multiple Instances
You can sync consumer keys to multiple instances in the Global View consumer management.
1. In the left sidebar, click Consumer Management, and switch between the Consumer Group / Consumer / Consumer Key tabs as needed.
2. Create a consumer group and a consumer, and enter the name, description, and credential type.
3. On the Consumer Key Tab, click Create and enter the following parameters:
Credential Name: Enter the credential name.
Associated Consumer: Select the associated consumer.
Credential Type: Select API Key or JWT Secret.
4. Click Create and Sync to Instances to open the sync dialog. Select the instances as needed to sync the key to multiple instances.
FAQs
Configuration and Usage
Q1: How to Choose the Appropriate Authentication Method?
Select an option based on your actual scenario:
API Key: It is suitable for simple scenarios, such as internal services or trusted clients. It is easy to configure and offers optimal performance.
JWT: It is designed to transmit user identity information, supports custom Claims, and is suitable for inter-microservice calls.
OAuth 2.0: It requires integration with third-party OAuth services and supports the standard OAuth flow.
OIDC: It requires user identity authentication and supports SSO (Single Sign-On).
Q2: Can a Single Consumer Be Configured with Multiple Credentials?
Yes. A single consumer supports configuring multiple types of credentials simultaneously, for example:
Credential 1: API Key type.
Credential 2: JWT type.
Credential 3: OAuth 2.0 type.
The client can select which credential to use for accessing the API based on the actual situation.
Q3: How to Choose the Signature Algorithm for JWT?
HS256 (symmetric encryption): It uses a key (Secret) for signing and verification, is easy to configure, offers optimal performance, and is suitable for internal services.
RS256/ES256 (asymmetric encryption): It uses a private key for signing and a public key for verification, is more secure, and is suitable for scenarios that require public key distribution.
If the JWT is issued by a third-party service, you must configure it according to the signature algorithm used by that service.
Feature Limitations
Q1: What Is the Maximum Number of Key Credentials That Can Be Configured for a Single Consumer?
A single consumer can configure up to 20 credentials, supporting mixed configurations of multiple types.
Q2: What Authorization Modes Does OAuth 2.0 Support?
The following authorization modes are currently supported:
Client Credentials (Client Credentials mode): It is used for machine-to-machine (M2M) scenarios.
Password (Password mode): It is used for trusted client scenarios.
The Implicit (implicit mode), Authorization Code, and Refresh Token flows are not supported yet.
Tutorials
Q1: How to Manage Authentication Credentials in a Production Environment?
Recommended management practices:
1. Credential Rotation: Rotate credentials periodically (for example, quarterly) to reduce the risk of credential leakage.
2. Validity Period Setting: Set a reasonable validity period for credentials (for example, one year) to prevent permanently valid credentials from being continuously abused after leakage.
3. Permission Separation: Create distinct consumers for different business systems to avoid sharing credentials.
4. Monitoring and Alarming: Monitor the authentication failure rate and promptly alarm on abnormal traffic.
5. Credential Storage: Store credential information in a configuration center or a key management service. Do not hardcode it in the code.
6. Leakage Response: If a credential is leaked, immediately disable or delete it and create a new one.