Updated on 2026-09-21 GMT+08:00

Creating a Grant

Function

This API is used to create a grant. Granted users can perform operations on the granted keys. The service default CMK whose suffix is /default cannot be granted.

Calling Method

For details, see Calling APIs.

URI

POST /v1.0/{project_id}/kms/create-grant

**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. 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
key_id	Yes	String	Definition Key ID Constraints The value must be a 36-byte ID. 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}$. Range N/A Default Value N/A
grantee_principal	Yes	String	Definition Granted user ID Constraints The value must contain 1 to 64 bytes. The value must match the regular expression ^[a-zA-Z0-9]{1,64}$. Range N/A Default Value N/A
operations	Yes	Array of strings	Definition List of granted operations Constraints The value cannot contain only create-grant. Range create-datakey: Create a DEK. create-datakey-without-plaintext: Create a plaintext-free DEK. encrypt-datakey: Encrypt a DEK. decrypt-datakey: Decrypt a DEK. describe-key: Query key information. retire-grant: Retire a grant. encrypt-data: Encrypt data. decrypt-data: Decrypt data. Default Value N/A
name	No	String	Definition Grant name Constraints The value must contain 1 to 255 characters. The value must match the regular expression ^[a-zA-Z0-9:/_-]{1,255}$. Range N/A Default Value N/A
retiring_principal	No	String	Definition ID of the user who can retire a grant Constraints The value must contain 1 to 64 bytes. The value must match the regular expression ^[a-zA-Z0-9]{1,64}$. Range N/A Default Value N/A
grantee_principal_type	No	String	Definition Grant type Constraints N/A Range user: Grant to a sub-user. domain: Grant to a tenant account. Default Value user
sequence	No	String	Definition A 36-byte serial number of a request message, for example, 919c82d4-8046-4722-9094-35c3c6524cff. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
grant_id	String	Definition Grant ID Range N/A

Example Requests

Grant user 13gg44z4g2sglzk0egw0u726zoyzvrs8 with permission to query, create, and encrypt a key whose ID is 0d0466b0-e727-4d9c-b35d-f84bb474a37f.

{
  "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f",
  "operations" : [ "describe-key", "create-datakey", "encrypt-datakey" ],
  "grantee_principal" : "13gg44z4g2sglzk0egw0u726zoyzvrs8",
  "grantee_principal_type" : "user",
  "retiring_principal" : "13gg44z4g2sglzk0egw0u726zoyzvrs8"
}

Example Responses

Status code: 200

Request succeeded.

{
  "grant_id" : "7c9a3286af4fcca5f0a385ad13e1d21a50e27b6dbcab50f37f30f93b8939827d"
}

Status Codes

Status Code	Description
200	Request succeeded.

Error Codes

See Error Codes.

Parent Topic: Key Grant Management