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 specify a symmetric CMK to encrypt secrets. If the kms_key_id parameter is not specified, the default master key csms/default will be used to encrypt the secrets created under your account in a project. If the CMK you specified does not exist under your account, it will be automatically created.

To use a specified CMK, you need to obtain the corresponding kms:dek:create permission to encrypt secret values.

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
csms:secret:create	Write	secretName *	csms:Type csms:KmsKeyId	-	kms:cmk:createDataKey
csms:secret:create	Write	-	g:EnterpriseProjectId g:RequestTag/<tag-key> g:TagKeys	-	kms:cmk:createDataKey

URI

POST /v1/{project_id}/secrets

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID. For details, see Obtaining a Project ID. Constraints N/A Range The value returned by the IAM API is used, which contains 32 characters. Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. It can be obtained by calling the IAM API. The value of X-Subject-Token in the response header is the user token. This parameter is optional if AK/SK authentication is used. Constraints N/A Range Obtain the value by calling the IAM API for obtaining the user token. Default Value N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
name	Yes	String	Definition Name of the secret to be created Constraints N/A Range The value must match the regular expression ^[a-zA-Z0-9_-]{1,64}$. Default Value N/A
kms_key_id	No	String	Definition ID of the KMS CMK used to encrypt secrets. If this parameter is not specified, the default master key csms/default will be used. If the CMK you specified does not exist under your account, it will be automatically created. Constraints N/A Range The value must match the regular expression ^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}$. Default Value N/A
description	No	String	Definition Secret description Constraints N/A Range N/A Default Value N/A
secret_binary	No	String	Definition Plaintext of a binary secret encoded using Base64. CSMS encrypts the plaintext and stores it in the initial version of the secret. Constraints Either secret_binary or secret_string must be configured. The maximum size is 64 KB. Range N/A Default Value N/A
secret_string	No	String	Definition Plaintext of a text secret. CSMS encrypts the plaintext and stores it in the initial version of the secret. Constraints Either secret_binary or secret_string must be configured. The maximum size is 64 KB. Range N/A Default Value N/A
secret_type	No	String	Definition Secret type Constraints N/A Range COMMON: shared secret (default). It is used to store sensitive information in an application system. RDS: RDS secret. It is used to store RDS account information. (This value is no longer supported and is replaced by RDS-FG.) RDS-FG: RDS secret. It is used to store RDS account information. GaussDB-FG: TaurusDB secret. It is used to store TaurusDB account information. Default Value COMMON
auto_rotation	No	Boolean	Definition Automatic rotation. This parameter can be configured only for secrets of specific types. Constraints N/A Range true: enabled, false: disabled (default) Default Value false
rotation_period	No	String	Definition Rotation period. This parameter is mandatory when automatic rotation is enabled. Constraints Integer[unit]. Integer indicates the time length. unit indicates the time unit, which can be d (day), h (hour), m (minute), or s (second). For example, 1d and 24h indicate one day. Range 4 hours to 8,760 hours (365 days) Default Value N/A
rotation_config	No	String	Definition Rotation configuration Constraints The value can contain a maximum of 1,024 characters. This parameter is mandatory when secret_type is RDS-FG or GaussDB-FG. The parameter format is {"InstanceId":"","SecretSubType":""}. Definition: InstanceId indicates the instance ID, and SecretSubType indicates the rotation subtype. The value can be SingleUser or MultiUser. SingleUser: Single-user rotation is used. A new password is created for the account for each rotation. MultiUser: Multi-user rotation is used. The users are labeled as SYSCURRENT and SYSPREVIOUS, respectively. During secret rotation, the password of the user labeled by SYSPREVIOUS will be reset to a random one. Then, the user labels of SYSCURRENT and SYSPREVIOUS are exchanged. Range N/A Default Value N/A
event_subscriptions	No	Array of strings	Definition Events to which a secret is subscribed. When a basic event is triggered, a message is sent to the topic corresponding to the event. Constraints Currently, only one event can be subscribed to. Range N/A Default Value N/A
enterprise_project_id	No	String	Definition This parameter is available for enterprise users. If you are an enterprise user and have created an enterprise project, select the required enterprise project from the drop-down list. The default project is default. Constraints If you have not enabled enterprise management, this parameter will not be displayed. Range N/A Default Value For an enterprise project user, the default value is 0.
rotation_func_urn	No	String	Definition Secret rotation function, which is the URN of the FunctionGraph function. This parameter is mandatory when automatic rotation is enabled. Constraints A secret rotation function has been created. Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
secret	Secret object	Definition Secret details. Range N/A

**Table 5** Secret
Parameter	Type	Description
id	String	Definition Secret ID Range N/A
name	String	Definition Secret name Range N/A
state	String	Definition Secret status Range ENABLED DISABLED PENDING_DELETE FROZEN
kms_key_id	String	Definition ID of the KMS CMK used to encrypt secret values Range N/A
description	String	Definition Secret description Range N/A
create_time	Long	Definition Timestamp when a secret was created, that is, total number of seconds since January 1, 1970. Range N/A
update_time	Long	Definition Timestamp when a secret was last updated, that is, the total number of seconds since January 1, 1970. Range N/A
scheduled_delete_time	Long	Definition Timestamp when a secret is to be deleted as scheduled, that is, total number of seconds since January 1, 1970. If a secret is not in the Pending deletion state, the value of this parameter is null. Range N/A
secret_type	String	Definition Secret type Range COMMON: shared secret (default). It is used to store sensitive information in an application system. RDS: RDS secret. It is used to store RDS account information. (This value is no longer supported and is replaced by RDS-FG.) RDS-FG: RDS secret. It is used to store RDS account information. GaussDB-FG: TaurusDB secret. It is used to store TaurusDB account information.
auto_rotation	Boolean	Definition Automatic rotation Range true: enabled, false: disabled (default)
rotation_period	String	Definition Rotation period Range 4 hours to 8,760 hours (365 days)
rotation_config	String	Definition Rotation configuration Range The value can contain at most 1,024 characters. If secret_type is set to RDS-FG or GaussDB-FG, set this parameter to {"InstanceId":"","SecretSubType":""}. Note: This parameter is mandatory when secret_type is set to RDS-FG or GaussDB-FG. InstanceId indicates the instance ID, and SecretSubType indicates the rotation subtype. The value can be SingleUser or MultiUser. SingleUser: Single-user rotation is used. A new password is created for the account for each rotation. MultiUser: Multi-user rotation is used. The users are labeled as SYSCURRENT and SYSPREVIOUS, respectively. During secret rotation, the password of the user labeled by SYSPREVIOUS will be reset to a random one. Then, the user labels of SYSCURRENT and SYSPREVIOUS are exchanged.
rotation_time	Long	Definition Rotation timestamp. Range N/A
next_rotation_time	Long	Definition Next rotation timestamp. Range N/A
last_used_time	Long	Definition Time when the secret value was last obtained. Range N/A
event_subscriptions	Array of strings	Definition Events to which a secret is subscribed. Currently, only one event can be subscribed to. When a basic event is triggered, a message is sent to the topic corresponding to the event. Range N/A
enterprise_project_id	String	Definition Enterprise project ID. Range N/A
rotation_func_urn	String	Definition URN of the FunctionGraph function Range N/A
domain_id	String	Definition ID of the tenant to which the secret belongs. Range N/A
replica_type	String	Definition Multi-region secret type Range STANDALONE: There is no multi-region replica for the current secret. PRIMARY: There are multi-region replicas for the current secret. This secret is the primary one. REPLICA: There are multi-region replicas for the current secret. This secret is the replica one.
replicas	Array of Replica objects	Definition Replica secret information. Range N/A

**Table 6** Replica
Parameter	Type	Description
id	String	Definition Secret ID Range N/A
kms_key_id	String	Definition ID of the KMS key used to encrypt secret values Range N/A
project_id	String	Definition ID of the project to which the secret belongs Range N/A
region	String	Definition Name of the region to which the secret belongs Range N/A
replica_type	String	Definition Multi-region secret type Range PRIMARY: primary secret REPLICA: replica secret
status	String	Definition Replica secret synchronization status Range IN_PROGRESS: The replica secret is to be synchronized. IN_SYNC: The replica secret is synchronized with the primary secret. FAILED: The replica secret fails to be synchronized with the primary secret.
created_at	Long	Definition Creation timestamp. Range N/A
updated_at	Long	Definition Update timestamp. Range N/A

Example Requests

Create a secret named demo. Encrypt the secret value this is a demo secret string using a KMS key whose ID is 0d0466b0-e727-4d9c-b35d-f84bb474a37f.

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

Example Responses

Status code: 200

Request 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,
    "secret_type" : "RDS-FG",
    "auto_rotation" : true,
    "rotation_config" : "{'InstanceId':'63616bceef2c45409575d762a498318bin01','SecretSubType':'MultiUser'}",
    "rotation_period" : "1d",
    "rotation_time" : 1668567940000,
    "next_rotation_time" : 1668629140000,
    "event_subscriptions" : [ "pocEvent" ],
    "rotation_func_urn" : "urn:fss:{region}:46b6f338fc3445b8846c71dfb1fbxxxx:function:default:test2-0:latest"
  }
}