To connect a self-managed application to KMS using KMS Instance SDK or a secret SDK, create an application access point (AAP) and generate a client key. The client key authenticates your application and controls which KMS resources it can access.
Prerequisites
Before you begin, ensure that you have:
A purchased and enabled KMS instance. See Purchase and enable a KMS instance
At least one key or secret created. See Getting started with Key Management and Getting started with Secrets Manager
Choose a creation mode
The KMS console offers two modes. Use the following table to pick the right one before you start.
| Quick creation | Standard creation | |
|---|---|---|
| Endpoint access | KMS instance endpoint only | KMS instance endpoint (keys and secrets) + KMS public or virtual private cloud (VPC) endpoint (secrets only) |
| Client key validity | Fixed at 5 years | Configurable — set to 1 year |
| Accessible resources | All keys and secrets in the KMS instance (you can modify the permission policy after creation) | Configurable per permission policy |
| Network access control | Not available | Configurable via network access rules |
| Best for | Quick SDK integration with minimal setup | Production applications requiring fine-grained access control |
Change your client key before it expires to prevent access interruptions. For details, see Change a client key. Create one AAP per application so each application has independent access permissions.
Use the KMS console
Quick creation
Use quick creation to get an application connected to KMS with minimal configuration steps. All keys and secrets in the selected KMS instance are accessible by default.
Log in to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Application Access > AAPs.
On the Application Access tab, click Create AAP.
In the Create AAP panel, set the following parameters and click OK.
Parameter Description Mode Select Quick Creation. Scope (KMS Instance) Select the KMS instance your application needs to access. Application Access Point Name Enter a name for the AAP. Authentication Method Fixed as ClientKey. Default Permission Policy Fixed as key/*secret/*. Your application can access all keys and secrets in the selected KMS instance.
The browser automatically downloads two files:
clientKey_****.json— contains the Application Access Secret (ClientKeyContent)clientKey_****_Password.txt— contains the Password
Store both files securely.
Standard creation
Standard creation lets you define exactly which resources an application can access, from which networks, and for how long. Complete the following three steps in order.
Step 1: Create a network access rule
A network access rule defines which source IP addresses can reach your KMS instance.
Skip this step if you do not need source IP filtering. For production environments, configure network access rules to restrict access.
On the AAPs page, click the Network Access Rules tab, then click Create Network Access Rule.
In the Create Network Access Rule panel, set the following parameters and click OK.
Parameter Description Rule Name A name for the network access rule. Network Type See the endpoint and network type reference below to choose the correct type. Allowed Source IP Addresses The IP addresses from which access is allowed. If your application runs behind a proxy server, enter the proxy server's IP address. See details in the reference table below. Description (Optional) A description for the rule. Allowed source IP addresses by network type:
Network type Allowed source IP addresses Private IP addresses in the VPCs associated with your KMS instance Public Public IP addresses VPC VPC IDs and IP addresses within those VPCs
Endpoint and network type reference
Use this table to match your SDK and use case to the correct network type.
| Use case | SDK | Network type | Regions |
|---|---|---|---|
| Cryptographic operations (encrypt, decrypt, sign, verify) | KMS Instance SDK | Private | All regions |
| Secret retrieval — high throughput, high security | KMS Instance SDK | Private | All regions |
| Secret retrieval via shared gateway | Secret SDK | Private, Public, or VPC | Private and Public: all regions; VPC: China (Hangzhou), China (Shanghai), China (Shenzhen), China (Zhangjiakou) |
Cryptographic operations require KMS Instance SDK with a KMS instance endpoint. Set the network type to Private and restrict allowed source IP addresses to VPC addresses associated with your KMS instance.
Step 2: Create a permission policy
A permission policy defines which keys or secrets an application can access and which operations it can perform.
Click the Policies tab, then click Create Policy.
In the Create Policy panel, set the following parameters and click OK.
Parameter Description Policy Name A name for the permission policy. Scope If the network type is Private, select the specific KMS instance. If the network type is Public or VPC, select Shared KMS Gateway. RBAC Permissions Select the role that matches your application's needs. See the RBAC roles reference below. Accessible Resources The keys or secrets your application needs to access. To specify multiple secrets whose combined name length exceeds the limit, use wildcards. For example, secret/rds-ibm*matches all secrets with the prefixrds-ibm.Network Access Rules Select the network access rule you created in step 1. Leave blank if you are not using source IP filtering. Description (Optional) A description for the policy.
RBAC roles reference
| Role | Scope | Operations allowed |
|---|---|---|
| CryptoServiceKeyUser | Specific KMS instance | Use keys for cryptographic operations. See Key-related operations. |
| CryptoServiceSecretUser | Specific KMS instance | Use secrets in the KMS instance. See Secret-related operations. |
| SecretUser | Shared KMS Gateway | Use all secrets in the current account. Supports the GetSecretValue operation. |
Assign the minimum role required for your application. If your application only retrieves secrets, assign CryptoServiceSecretUser (or SecretUser for Shared KMS Gateway) rather than CryptoServiceKeyUser.
Step 3: Create the AAP
Click the Application Access tab, then click Create AAP.
In the Create AAP panel, set the following parameters and click OK.
Parameter Description Mode Select Standard Creation. Application Access Point Name Enter a name for the AAP. Authentication Method Select ClientKey or RAMRole. This example uses ClientKey. Encryption Password Enter a password for the client key. Must be 8–64 characters and contain at least two of the following types: digits, letters, and special characters ( ~ ! @ # $ % ^ & * ? _ -).Validity Period Set to 1 year. Change the client key before expiration to keep your application connected. See Change a client key. Policies Select the permission policy you created in step 2. Description (Optional) A description for the AAP.
The browser automatically downloads two files:
clientKey_****.json— contains the Application Access Secret (ClientKeyContent)clientKey_****_Password.txt— contains the Password
Store both files securely.
Call API operations
To create an AAP programmatically, call the following operations in order:
Call CreateNetworkRule to create a network access rule. Specify the private IP addresses or private CIDR blocks from which access to KMS is allowed.
Call CreatePolicy to create a permission policy. Specify the keys and secrets to allow and the network access rules to apply.
Call CreateApplicationAccessPoint to create the AAP. Specify the authentication method and permission policies.
Call CreateClientKey to generate a client key. Specify the encryption password, validity period, and AAP.
Use Terraform
For Terraform-based setup, see Create an AAP with Terraform.
Configure your SDK after creating an AAP
If the AAP scope is a specific KMS instance (not Shared KMS Gateway), configure the instance CA certificate and instance endpoint in your SDK before making API calls.
Get the instance CA certificate
The KMS instance uses HTTPS with a built-in SSL/TLS certificate. Download the instance CA certificate to verify the KMS instance's SSL/TLS certificate during SDK initialization.
KMS instances support TLS 1.2 only.
On the Instances page, click the Software Key Management or Hardware Key Management tab and find your instance.
Click the instance ID or Details in the Actions column.
On the instance details page, click Download next to Instance CA Certificate.
The downloaded file is named PrivateKmsCA_kst-******.pem by default. Store it securely alongside your client key files.
Get the instance endpoint
On the Instances page, click the Software Key Management or Hardware Key Management tab and find your instance.
Click the instance ID to open the details page.
Copy the Instance VPC Endpoint value and remove the
https://prefix. The remaining string is the endpoint to pass to your SDK.
What's next
Manage an AAP — update accessible resources, delete unused AAPs
Change a client key — rotate keys before they expire (recommended: every year)
Alert events — KMS sends alerts when a client key is approaching expiration; act on them promptly