Reference a key - API Gateway - Alibaba Cloud Documentation Center

You can use keys for resources such as consumers, AI services, Agent services, MCP services, and plugins. Keys replace plaintext credentials to prevent credential leaks. This topic describes how to reference a key in these resources.

Prerequisite

A key must be created. For more information about creating a key, see Create a key.

Important

Key referencing is supported in AI Gateway 2.1.11 and later.

Reference a key in a consumer

Go to the AI Gateway console. In the navigation pane on the left, choose Consumers. In the top menu bar, select a region.
Click Create Consumer. In the Create Consumer panel, enter a name for the consumer. Set Authentication Method to API Key and Generation Method to Reference Key. Then, set Bind Key to an existing key.
Note
Key referencing for consumer credentials is supported only when you use the API key authentication method.

Reference a key in an AI service

Go to the AI Gateway console. In the navigation pane on the left, choose Instance. In the top menu bar, select a region.
Click the ID of the target instance. In the navigation pane on the left, choose Service, and then click Create Service.
In the Create Service panel, set Service Source to AI Services. In the Large Model Configuration section, set Generation Method to Reference Key. Then, set API-KEY to an existing key.

Reference a key in an Agent service

Go to the AI Gateway console. In the navigation pane on the left, choose Instance. In the top menu bar, select a region.
Click the ID of the target instance. In the navigation pane on the left, choose Service, and then click Create Service.
In the Create Service panel, set Service Source to Agent Services. Set Generation Method to Reference Key. Then, set API-KEY to an existing key.

Reference a key in an MCP service

MCP services that are directly proxied by AI Gateway support backend authentication. In the authentication configuration, you can specify an existing key as the credential.

Go to the AI Gateway console. In the navigation pane on the left, choose Instance. In the top menu bar, select a region.
Click the ID of the target instance. Click MCP Management. Then, create an MCP service for the direct proxy scenario. For more information, see Create a gateway-hosted MCP service.
Go to the MCP service details page. On the Basic Information page, click Configure Backend Service Authentication and configure the following settings to enable authentication.
1. Authentication Method: Select API Key.
2. Credential Source: Custom HTTP Header.
3. Header: The name of the header that carries the credential.
4. Generation Method: Select Reference Key.
5. Credential: Select an existing key.

Reference a key in a plug-in

In the plugin configuration, you can use the $ref{secretName} syntax to reference a key, where secretName is the name of the key. The following code provides a configuration example for the Key-Auth plugin:

credentials: 
# Reference the key named secretName
- $ref{secretName}
keys:
- apikey
- x-api-key

With this configuration, you can use the secretName key to access AI Gateway. Both official and custom plugins support key referencing.

View key reference details

Go to the AI Gateway console. In the navigation pane on the left, choose Key. In the Referenced column, click the number for a key to view the resources that reference it.