Using gRPC with Cloud KMS

If you are using manually created gRPC libraries to make calls to Cloud KMS, you must specify a x-google-request-params value in the metadata, or header, of the call. The proper use of x-google-request-params will route the call to the appropriate region for your Cloud KMS resources.

Set the x-google-request-params value to a field in the method's request as shown in the following table.

Method Request field
CreateCryptoKey CreateCryptoKeyRequest.parent
CreateCryptoKeyVersion CreateCryptoKeyVersionRequest.parent
CreateKeyRing CreateKeyRingRequest.parent
ListCryptoKeyVersions ListCryptoKeyVersionsRequest.parent
ListCryptoKeys ListCryptoKeysRequest.parent
ListKeyRings ListKeyRingsRequest.parent

Setting the request field

The following examples show where to specify the resource name in various methods. Replace the text styled as PLACE_HOLDER with the actual values used in your Cloud KMS resource IDs.

Decrypt example

If you are making a call to Decrypt, you need to populate the following fields in your request:

name: 'projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY/'
ciphertext: 'iQALWM/r6alAxQm0VQe3...'

The value assigned to the name field is the resource name of your CryptoKey. To properly route the call, you must also include this resource name in the call metadata, in the following form:

x-goog-request-params: 'name=projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY/'

CreateKeyRing example

If you are making a call to CreateKeyRing, you need to populate the following fields in your request:

parent: 'projects/PROJECT_ID/locations/LOCATION/'
key_ring_id: 'myKeyRing'

The call metadata also needs to contain the parent resource name:

x-goog-request-params: 'parent=projects/PROJECT_ID/locations/LOCATION/'

UpdateCryptoKey example

If you are making a call to UpdateCryptoKey, you need to populate the following fields in your request:

name: 'projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY/'
field_mask: ...

The metadata also needs to contain the name resource name. Note the format uses, not name=:

x-goog-request-params: ''

Adding metadata using C++

If you are using C++, call ClientContext::AddMetadata before making your RPC call to add the appropriate information to the call metadata.

For example, if you are adding metadata for a call to Decrypt:


You can then pass the context to your method call as usual, along with your request and response protocol buffers.

Was this page helpful? Let us know how we did:

Send feedback about...