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

Retiring a Grant

Function

Description: This API is used to retire a grant. After a grant is retired, the grantee no longer has the permission to perform operations on the granted key. For example, user A grants operation permissions on CMK A/key to user B and authorizes user C to retire the grant. By doing this, users A, B, and C can all cancel the permissions. After the canceling, user B does not have permissions on CMK A/key anymore.
Note: The following users can retire a grant:
User who created the grant
User specified by retiring_principal
User specified by grantee_principal in a grant list that contains retire-grant

Calling Method

For details, see Calling APIs.

URI

POST /v1.0/{project_id}/kms/retire-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
grant_id	Yes	String	Definition Grant ID Constraints The value must contain 64 bytes. The value must match the regular expression ^[A-Fa-f0-9]{64}$. Range N/A Default Value N/A
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

Request succeeded.

None

Example Requests

Delete the grant (ID: 7c9a3286af4fcca5f0a385ad13e1d21a50e27b6dbcab50f37f30f93b8939827d) for the key whose ID is 0d0466b0-e727-4d9c-b35d-f84bb474a37f.

{
  "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f",
  "grant_id" : "7c9a3286af4fcca5f0a385ad13e1d21a50e27b6dbcab50f37f30f93b8939827d"
}

Example Responses

None

Status Codes

Status Code	Description
200	Request succeeded.

Error Codes

See Error Codes.

Parent Topic: Key Grant Management