All Products
Search

This Product

    Key Management Service:Credentials SDK

    Document Center

    Key Management Service:Credentials SDK

    Last Updated:Jun 03, 2026

    The Credentials SDK wraps KMS OpenAPI and instance APIs to cache and refresh credentials in your applications, improving stability and simplifying integration.

    Integration overview

    The Credentials SDK only supports retrieving credential values. It supports access through shared gateways and dedicated gateways.

    image

    Shared vs. dedicated gateways

    The Credentials SDK retrieves credentials through shared or dedicated gateways. A shared gateway is the KMS global network, accessible over the Internet or VPC networks. A dedicated gateway serves a specific KMS instance and only supports access over private networks.

    Difference

    Shared Gateway

    Dedicated Gateway

    Recommended scenarios

    • No strict credential retrieval performance requirements.

    • Business is deployed outside Alibaba Cloud VPCs.

    • Non-production environments, such as internal testing.

    • Business is deployed within Alibaba Cloud VPCs.

    • Frequent credential retrieval.

    • High data security requirements.

    Network

    Internet or VPC network.

    KMS private network.

    Performance

    Example: shared gateway encryption/decryption QPS is 1,000.

    Based on the computing performance specifications of the purchased instance, such as 1,000 or 2,000. For more information, see

    Client initialization configuration

    • Endpoint: shared gateway endpoint, such as kms.cn-hangzhou.aliyuncs.com. For more information, see SDK Overview.

    • KMS instance CA certificate: not required.

    • Endpoint: dedicated gateway endpoint, in the format of <YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com.

      Example: kst-hzz65f176a0ogplgq****.cryptoservice.kms.aliyuncs.com.

    • KMS instance CA certificate: required.

    API availability

    OpenAPI-GetSecretValue

    OpenAPI-GetSecretValue , Instance API-GetSecretValue (not recommended)

    Authentication and Authorization

    The Credentials SDK supports two authentication methods: RAM authentication and AAP authentication (not recommended).

    Authentication Method

    Supported Credential Types

    RAM authentication

    RamRoleArn, ECS RAM role, STS token, AccessKey, Alibaba Cloud default credential chain, OIDC Role ARN, and more.

    Note

    The RAM credentials plugin only supports ECS RAM roles.

    AAP authentication (not recommended)

    ClientKey (shared gateway configuration), ClientKey (dedicated gateway configuration)

    SDK types

    The Credentials SDK includes three SDK types: credentials client, credentials JDBC client, and RAM credentials plugin. Each retrieves KMS credential values through shared or dedicated gateways. Supported authentication methods and APIs vary by type.

    SDK Type

    Description

    Gateway and Authentication

    Secrets Manager Client

    • Supports all credential types.

    • Caches and refreshes credentials automatically for higher stability.

    Shared gateway and dedicated gateway: RamRoleArn, ECS RAM role, STS token, AccessKey, Alibaba Cloud default credential chain, OIDC Role ARN, ClientKey, and more.

    Note

    We recommend that you use credentials client V2 SDK. For more information about version differences, see Secrets Manager Client.

    Secret JDBC client

    • Requires Java 8 or later.

    • Only supports RDS credentials and general credentials whose values are in the {"AccountName":"<your-database-username>","AccountPassword":"<your-database-password>"} format.

    • When connecting through JDBC, connection pools (c3p0, DBCP), or open-source database frameworks, use the credentials JDBC client for authentication and custom credential refresh intervals.

    Shared gateway:

    • RAM authentication: RamRoleArn, ECS RAM role, STS token, AccessKey.

    • AAP authentication (not recommended): ClientKey (shared gateway configuration).

    Dedicated gateway (not recommended):

    AAP authentication: ClientKey (dedicated gateway configuration).

    RAM secret plug-in

    • Only supports RAM credentials.

    • Your business application must use an SDK version supported by this plugin. For more information, see Supported SDKs.

    Shared gateway:

    • RAM authentication: ECS RAM role.

    • AAP authentication (not recommended): ClientKey (shared gateway configuration).

    Dedicated gateway (not recommended):

    AAP authentication: ClientKey (dedicated gateway configuration).

    Supported APIs

    API

    Description

    Shared Gateway

    Dedicated Gateway

    GetSecretValue (OpenAPI)

    Retrieves a credential value.

    Supported

    Supported

    GetSecretValue (Instance API)

    Retrieves a credential value.

    Unsupported

    Supported

    Supported programming languages

    Supported programming languages and SDK documentation for each type:

    Credentials SDK

    Supported Language

    Secrets Manager Client

    Java (Java 8 or later), Python, Go

    Secret JDBC client

    Java (Java 8 or later)

    RAM secret plug-in

    Java (Java 8 or later), Python, Go