All Products
Search

This Product

    Key Management Service:Manage and use generic secrets

    Document Center

    Key Management Service:Manage and use generic secrets

    Last Updated:Aug 25, 2026

    Generic secrets store sensitive data such as passwords, AccessKey pairs, OAuth keys, and tokens in KMS. Multiple versions let you rotate values without hard-coding credentials.

    Generic secret rotation

    KMS does not support periodic rotation for generic secrets. To set up periodic rotation, use Use Function Compute to rotate a generic secret. To rotate immediately, store a new version in the console or call the PutSecretValue OpenAPI operation.

    Warning

    Each generic secret supports up to 10 versions. KMS automatically deletes the oldest version when this limit is exceeded.

    Prerequisites

    Step 1: Create a secret

    When you create a generic secret, KMS assigns the built-in stage label ACSCurrent to the initial version.

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.

    2. Click the Generic Secrets tab, select an Instance ID, and then click Create Secret. Configure the parameters and click OK.

      Parameter

      Description

      Secret Name

      A custom credential name. Must be unique within the current region.

      Secret Value

      Select Secret Key/Value or Plain Text and enter the sensitive data to store. The value must be up to 30,720 bytes (30 KB) in length.

      Initial Version

      The initial version number. Default value: v1. Custom values are supported.

      CMK

      Select the symmetric key used to encrypt the credential value. The key and the credential must belong to the same KMS instance.

      Important

      • The key and the credential must belong to the same KMS instance, and the key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications.

      • If a RAM user or RAM role is used, it must have permissions to perform the GenerateDataKey operation using the encryption master key.

      Tags

      Add tags to the credential for classification. Each tag consists of a key-value pair.

      Note

      • Format of a tag key and a tag value: A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal signs (=), colons (:), at signs (@), and spaces.

      • A tag key cannot start with aliyun or acs:.

      • Each credential supports up to 20 tag key-value pairs.

      Description

      An optional description of the credential for identification and management.

      Advanced Settings > Policy Settings

      Set the access policy for the credential to control which RAM users or roles can read or modify it.

      You can select the default policy first and modify it later as needed.

    Step 2: Integrate the secret into your application

    Retrieve generic secret values through the GetSecretValue OpenAPI or GetSecretValue KMS Instance API (not recommended). Select a method by priority:

    Note

    • We recommend that you implement an error retry mechanism to improve service stability.

    • KMS supports multiple authentication methods. For higher security, we recommend that you use an ECS instance RAM role or a RAM role.

    • Endpoints:

      For a shared gateway, see Endpoints.

      For a dedicated gateway, use the following format: {Instance-ID}.cryptoservice.kms.aliyuncs.com.

    Priority

    Scenarios

    Supported gateway types

    Priority 1: Secrets Client

    Applications in Java 8+, Go, or Python.

    • Shared gateway

    • Dedicated gateway

    Priority 2: Alibaba Cloud SDK

    Applications in Java 6+, PHP, Go, Python, .NET (C#), C++, or Node.js.

    • Dedicated gateway (recommended)

    • Shared gateway

    Priority 3: KMS Agent

    • Large-scale co-deployed applications that access KMS.

    • KMS Agent exposes standard HTTP interfaces and supports any programming language.

    • Dedicated gateway (recommended)

    • Shared gateway

    Priority 4: KMS Instance SDK (not recommended)

    Applications in Java 8+, PHP, Go, Python, or .NET (C#).

    Dedicated gateway

    Additional operations

    Rotate a generic secret

    Rotation cannot be configured during secret creation. To rotate immediately, store a new version in the console or call the PutSecretValue OpenAPI operation.

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.

    2. Click the Generic Secrets tab, select an Instance ID, find the target secret, and then click Details in the Actions column.

    3. On the secret details page, in the Versions section, click Store Secret Value.

    4. In the Store Secret Value dialog box, enter values for Version and Secret Value, and then click OK.

      Important

      Storing a new version rotates the secret immediately. The GetSecretValue API returns the latest version by default.

    Delete a generic secret

    Delete a generic secret by scheduling deletion or removing it immediately.

    Warning

    Verify that the secret is no longer in use before deletion. Active references to a deleted secret may cause service failures.

    1. Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Secrets.

    2. Click the Generic Secrets tab, select an Instance ID, find the target secret, and then click Schedule Deletion in the Actions column.

    3. In the Schedule Deletion dialog box, select a deletion method for the secret and click OK.

      • Schedule Deletion: Specify a recovery period of 7 to 30 days. The system deletes the secret after the recovery period ends.

      • Delete Immediately: The system immediately deletes the secret.

      During the recovery period, you can find the secret and click Restore Secret in the Actions column to cancel the deletion.

    Configure tags for secrets

    Tags classify secrets as key-value pairs.

    Note

    • Format of a tag key and a tag value: A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal signs (=), colons (:), at signs (@), and spaces.

    • A tag key cannot start with aliyun or acs:.

    • Each credential supports up to 20 tag key-value pairs.

    Configure tags for a single secret

    Method

    Operation

    Method 1: Configure tags on the Secret Management page

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.

    2. Click the tab for the secret type, select an Instance ID, find the target secret, and then click the image.png icon in the Tag column.

    3. Click Modify. In the Edit Tags dialog box, enter one or more Tag Key and Tag Value pairs, click OK, and then click Close.

      You can also modify tag values or detach tags in batches.

    Method 2: Configure tags on the Secret Details page

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.

    2. Click the tab for the secret type, select an Instance ID, find the target secret, and then click Details in the Actions column.

    3. On the secret details page, click the image.png icon next to Tag.

    4. In the Edit Tags dialog box, enter one or more Tag Key and Tag Value pairs, click OK, and then click Close.

      You can also modify tag values or detach tags in batches.

    Configure tags for multiple secrets in a batch

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.

    2. Click the tab for the secret type, select an Instance ID, and then select the secrets that you want to manage.

      • Add tags: At the bottom of the secret list, click Add Tag. Enter one or more Tag Key and Tag Value pairs, click OK, and then click Close.

      • Remove tags: At the bottom of the secret list, click Remove Tag. In the Batch Remove dialog box, select the tags that you want to detach, click Cancel, and then click Close.