Help Center> Data Encryption Workshop> API Reference> APIs> Secret Management APIs> Lifecycle Management> Creating a Secret
View PDF

Creating a Secret

Function

This API is used to create a secret and store the secret value in the initial secret version.

Secret values are encrypted and stored in secret versions. A version can have multiple statuses. Versions without any statuses are regarded as deprecated versions and can be automatically deleted by CSMS.

The initial version is marked by the SYSCURRENT status tag.

Constraints

You can use a symmetric customer master key (CMK) to encrypt a secret. If the kms_key_id parameter is not specified, the default master key csms/default will be used to encrypt secrets. The default key is automatically created by CSMS.

To use a user-defined key to encrypt secrets, you need to have the kms:dek:create permission for the key.

Debugging

You can debug this API in API Explorer.

URI

POST /v1/{project_id}/secrets

Table 1 URI parameter

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID

Request Parameter

Table 2 Request header parameter

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token.

It can be obtained by calling the IAM API (value of X-Subject-Token in the response header).
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Secret name.

Constraint: The value can contain 1 to 64 characters and must match the regular expression ^[a-zA-Z0-9._-]{1,64}$.

kms_key_id

No

String

ID of the KMS CMK used to encrypt secrets. If this parameter is not specified, the default master key csms/default will be used. The default key is automatically created by CSMS.

description

No

String

Description of a secret.

Constraints: The value contains 2048 bytes.

secret_binary

No

String

Plaintext of a binary secret in Base64 format. CSMS encrypts it and stores it in the initial version of the secret.

Type: binary data object in Base64 format

Constraints: You must configure one and only one of secret_binary and secret_string. The maximum size is 32 KB.

secret_string

No

String

Plaintext of a binary secret in text format. CSMS encrypts it and stores it in the initial version of the secret.

Constraints: You must configure one and only one of secret_binary and secret_string. The maximum size is 32 KB.

Response Parameters

Status code: 200

Table 4 Response body parameter

Parameter

Type

Description

secret

Secret object

Secret
Table 5 Secret

Parameter

Type

Description

id

String

Secret ID

name

String

Secret name

state

String

Secret status. Its value can be:

ENABLED

DISABLED

PENDING_DELETE

FROZEN

kms_key_id

String

ID of the KMS CMK used to encrypt secret values

description

String

Description of a secret

create_time

Long

Secret creation time. The timestamp indicates the total seconds past the start of the epoch date (January 1, 1970).

update_time

Long

Time when a secret was last updated. The timestamp indicates the total seconds past the start of the epoch date (January 1, 1970).

scheduled_delete_time

Long

Time when a secret will be deleted as scheduled. The timestamp indicates the total seconds past the start of the epoch date (January 1, 1970).

If a secret is not in Pending deletion state, the value of this parameter is null.

Status code: 400

Table 6 Response body parameter

Parameter

Type

Description

error_code

String

Error Code

error_msg

String

Error description

Example Request

{
  "name" : "demo",
  "kms_key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f",
  "secret_string" : "this is a demo secret string"
}

Example Response

Status code: 200

The request has succeeded.

{
  "secret" : {
    "id" : "bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e",
    "name" : "test",
    "state" : "ENABLED",
    "kms_key_id" : "b168fe00ff56492495a7d22974df2d0b",
    "description" : "description",
    "create_time" : 1581507580000,
    "update_time" : 1581507580000,
    "scheduled_delete_time" : 1581507580000
  }
}

Status Code

Status Code

Description

200

The request has succeeded.

400

Invalid request parameters.

Error Code

For details, see Error Code.

Parent topic: Lifecycle Management