Reference keys

Prerequisites

You have an existing key. If not, create one as described in Create a key.

Reference a key in a consumer

1. Go to the AI Gateway console. In the navigation pane on the left, select Consumers. In the top menu bar, select a region.

2. Click Create a consumer. On the Create Consumer page, enter a consumer name. Set the authentication method to API key, the generation method to Reference Key, and select an existing key for Bind Key.

   Note

   For consumer credentials, only the API key authentication method supports key referencing.

Reference a key in an AI service

1. Go to the AI Gateway console. In the navigation pane on the left, select Instance. In the top menu bar, select a region.

2. Click the ID of the target instance. In the navigation pane on the left, select Service, and then click Create Service.

3. In the Create Service panel, set Service Source to AI Services. In the Large Model Configuration section, set the generation method to Reference Key and select an existing key for API Key.

Reference a key in an Agent service

1. Go to the AI Gateway console. In the navigation pane on the left, select Instance. In the top menu bar, select a region.

2. Click the ID of the target instance. In the navigation pane on the left, select Service, and then click Create Service.

3. In the Create Service panel, set Service Source to Agent Services, Generation Method to Reference Key, and select an existing key for API Key.

Reference a key in an MCP service

MCP services directly proxied by AI Gateway support backend authentication. You can specify an existing key as the backend credential.

1. Go to the AI Gateway console. In the navigation pane on the left, select Instance. In the top menu bar, select a region.

2. Click the target instance ID and create an MCP service for the direct proxy scenario as described in Create a gateway-hosted MCP service.

3. On the MCP service details page, click Configure Backend Service Authentication in Basic Information to enable authentication, and configure the following settings:

   1. Authentication method: Select API key.

   2. Credential source: Custom HTTP Header.

   3. Header: Specify the header name that carries the credential.

   4. Generation method: Select Reference Key.

   5. Credential: Select an existing key.

Reference a key in a plugin

Use the $ref{secretName} syntax in plugin configurations to reference a key, where secretName is the key name. Example Key-Auth plugin configuration:

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

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

View key references

Go to the AI Gateway console. In the navigation pane on the left, select Key. In the Referenced column, click a key's reference count to view which resources use it.