--- title: "Create Custom Key" slug: "security-kms-createusercustomkey" tags: ["Key Management Service", "KMS"] updated: 2026-09-17T10:25:45Z published: 2026-09-17T10:25:45Z canonical: "api.ncloud-docs.com/security-kms-createusercustomkey" --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Custom Key Available in Classic and VPC Create a randomized raw key that can be utilized as an encryption key. It can only be requested as an AES256 or RSA2048 key type. ## Request This section describes the request format. The method and URI are as follows: | Method | URI | | --- | --- | | POST | - API Gateway request signature v1: /keys/v1/{keyTag}/createCustomKey - API Gateway request signature v2: /keys/v2/{keyTag}/createCustomKey | ### Request headers For information about the headers common to all Key Management Service APIs, see [Key Management Service request headers](/docs/en/security-kms#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%941). ### Request path parameters You can use the following path parameters with your request: | Field | Type | Required | Description | | --- | --- | --- | --- | | `keyTag` | String | Required | Key tag - Unique identifier for the key derived from the key name - See [Get key list](/docs/en/security-kms2-key-list) - Use to request encryption or decryption with REST APIs - Key tags are not treated as confidential information | ### Request body You can include the following data in the body of your request: | Field | Type | Required | Description | | --- | --- | --- | --- | | `requestPlainKey` | Boolean | Optional | Whether to create encrypted random plaintext - `true` \| `false` (default) - `true`: create - `false`: not create | | `bits` | Integer | Optional | Size of the key data to create (bit) - `128` \| `256` (default) \| `512` | | `context` | String | Conditional | Base64-encoded string data - Required when using keys with convergent encryption - Can be up to 50 bytes long - Always generate the same ciphertext, even when encrypting the same data multiple times | ### Request example The request example is as follows: - API Gateway request signature v1 request ``` curl --location --request POST 'https://kms.apigw.ntruss.com/keys/v1/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6/createCustomKey' \ --header 'x-ncp-apigw-timestamp: {Timestamp}' \ --header 'x-ncp-apigw-api-key: {API Gateway API Key}' \ --header 'x-ncp-iam-access-key: {Sub Account Access Key}' \ --header 'x-ncp-apigw-signature-v1: {API Gateway Signature}' \ --data '{ "requestPlainKey": true, "bits": 256, "context": "{BASE64_CONTEXT}" }' ``` - API Gateway request signature v2 request ``` curl --location --request POST 'https://kms.apigw.ntruss.com/keys/v2/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6/createCustomKey' \ --header 'x-ncp-apigw-timestamp: {Timestamp}' \ --header 'x-ncp-iam-access-key: {Sub Account Access Key}' \ --header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \ --data '{ "requestPlainKey": true, "bits": 256, "context": "{BASE64_CONTEXT}" }' ``` ## Response This section describes the response format. ### Response body The response body includes the following data: | Field | Type | Required | Description | | --- | --- | --- | --- | | `code` | String | - | Success or Failure | | `msg` | String | - | Description of the response code (`code`) - Display an empty value ("") on request success (`SUCCESS`) | | `data` | Object | - | Response result | | `data.ciphertext` | String | - | String data created by encrypting a random plaintext | | `data.key_version` | Integer | - | Version of the created custom key | | `data.plaintext` | String or Array[String] | - | Plaintext data for the created custom key - Display if `requestPlainKey` is `true` - Base64-encoded | ### Response status codes For information about the HTTP status codes common to all Key Management Service APIs, see [Key Management Service response status codes](/docs/en/security-kms#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C1). ### Response example The response example is as follows: ``` { "code": "SUCCESS", "msg": "", "data": { "ciphertext": "{CIPHERTEXT}", "key_version": 3, "plaintext": "{BASE64_PLAINTEXT}" } } ```