Help Center/ Simple Message Notification/ API Reference/ APIs/ Key Management/ Binding a KMS Key to a Topic
Updated on 2025-11-21 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Binding a KMS Key to a Topic

Function

This API is used to bind a KMS key to a topic. A KMS key is applied 5 minutes later after being bound to a topic. After the KMS key is applied, all messages published to the topic, including subscription confirmation messages, subscription cancellation messages, and topic messages, are encrypted and decrypted using the data key of the specified key, and then transmitted in SMN. Before binding a KMS key, create an agency named smn_kms_agency on IAM and assign resource operation permissions to SMN. SMN uses this agency to create a data key.

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependencies

    smn:topic:createKmsKey

    Write

    topic *

    • g:EnterpriseProjectId

    • g:ResourceTag/<tag-key>

    -

    smn:topic:get

URI

POST /v2/{project_id}/notifications/topics/{topic_urn}/kms

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

The project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

topic_urn

Yes

String

Unique resource identifier of a topic. To obtain the resource identifier, see Querying Topics.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Specifies a user token.

It can be obtained by calling an IAM API. The value of X-Subject-Token in the response header is the user token.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

key_id

Yes

String

The ID of the customer master key created on DEW. For details, see Creating a Key.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

request_id

String

The unique request ID.

id

String

The ID of the used key. The ID is generated by SMN and is the unique ID of the key bound to the topic.

Status code: 400

Table 5 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the request ID, which is unique.

code

String

Specifies the error code.

message

String

Describes the error message.

Status code: 403

Table 6 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the request ID, which is unique.

code

String

Specifies the error code.

message

String

Describes the error message.

Status code: 404

Table 7 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the request ID, which is unique.

code

String

Specifies the error code.

message

String

Describes the error message.

Status code: 409

Table 8 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the request ID, which is unique.

code

String

Specifies the error code.

message

String

Describes the error message.

Status code: 500

Table 9 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the request ID, which is unique.

code

String

Specifies the error code.

message

String

Describes the error message.

Example Requests

Example request for binding a KMS key to a topic

https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:44ef0bd78eb24f02b40614fe85a7d234:topic_6b10aa8f904111f08c3584a93e8ae4b6/kms

{
  "key_id" : "9a618041-a917-49e0-bb3a-1a90163e97fe"
}

Example Responses

Status code: 200

Response body returned when the request succeeded.

{
  "request_id" : "44a8e3a585ab4da3954579f5d76ab626",
  "id" : "df9831e92dc24c289c0048170f61d5ad"
}

Status code: 400

Bad Request

{
  "request_id" : "12641f59208d4114a86aace62897980d",
  "error_code" : "SMN.00013056",
  "error_msg" : "The kms key id is not available."
}

Status code: 403

Forbidden

{
  "request_id" : "1b261437accc427da6c43eec2fc7e324",
  "code" : "SMN.0001",
  "message" : "No permission to request resources."
}

Status code: 404

Not Found

{
  "request_id" : "cfa7a869d1404329adff10ac4bea9308",
  "error_code" : "SMN.00010008",
  "error_msg" : "Topic information is not found."
}

Status code: 409

Conflict

{
  "request_id" : "03651b5ef1da4b3d9545036d2a954d7f",
  "error_code" : "SMN.00013049",
  "error_msg" : "Kms key already exists."
}

Status code: 500

Internal Server Error

{
  "request_id" : "cfa7a869d1404329adff10ac4bea9308",
  "error_code" : "SMN.00013054",
  "error_msg" : "Failed to save kms key."
}

Status Codes

Status Code

Description

200

Response body returned when the request succeeded.

400

Bad Request

403

Forbidden

404

Not Found

409

Conflict

500

Internal Server Error

Error Codes

See Error Codes.

Parent Topic: Key Management