Integration overview
The Instance API communicates over HTTP and uses Transport Layer Security (TLS) to secure all data in transit. To call an API operation, you send an HTTP POST request to KMS with the required parameters. The service then processes your request and returns a response. All requests and responses are encoded using Protocol Buffers. Protocol Buffers is a language-neutral, platform-neutral mechanism for serializing structured data that is smaller, faster, and simpler than XML. For more information, see Protocol Buffers.
Integration flow
Instance API call flow
-
The client generates the request data by encoding the request message according to its type definition.
-
The client sends the request data and its signature to KMS.
-
KMS verifies the signature and returns a response.
-
The client generates the response message by decoding the response data according to its type definition.
Endpoints
You access the Instance API through an Alibaba Cloud dedicated gateway over a private network. The endpoint format is <YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com. You can find your endpoint on the instance details page. For example, kst-hzz65f176a0ogplgq****.cryptoservice.kms.aliyuncs.com. In the KMS console, navigate to Instance Management in the left-side navigation pane. Click the target instance to go to its details page. In the Basic Information section, find the instance VPC endpoint field. This endpoint uses the format https://{instance-id}.cryptoservice.kms.aliyuncs.com.
Authentication
The Instance API supports only ClientKey authentication. To get a ClientKey, create an application access point (AAP).
If you create an application access point (AAP) by using the standard method, note the following:
-
In the network access rules section, set network type to Private.
-
In the policy section, set scope to your KMS instance ID.
Integration methods
Secrets SDK
The Secret SDK applies only to secret-related operations in the Instance API and simplifies calls to them. See Secret SDK for code examples that use ClientKey authentication.
Custom API wrapper calls (not recommended)
If you use native HTTP calls, you must manually construct and sign each request. You are responsible for implementing the signing algorithm as described in Request signature. In addition to the required business parameters, each request must include all common request headers. For a complete example, see V3 request body & signature mechanism.
KMS Instance SDK (not recommended)
The KMS Instance SDK simplifies development by handling the complex request signing process. You can make API calls by providing the required parameters and authentication information, which improves the readability and maintainability of your code. For code examples, see KMS Instance SDK (not recommended).