Using gRPC with Cloud KMS

If you are using manually createdgRPC libraries to make calls toCloud Key Management Service, you must specify ax-google-request-params value inthe metadata, or header, of the call. The proper use ofx-google-request-params will route the call to the appropriate region foryour Cloud KMS resources.

Set thex-google-request-params value to a field in the method's request asshown in the following table.

MethodRequest field
AsymmetricDecryptAsymmetricDecryptRequest.name
AsymmetricSignAsymmetricSignRequest.name
CreateCryptoKeyCreateCryptoKeyRequest.parent
CreateCryptoKeyVersionCreateCryptoKeyVersionRequest.parent
CreateImportJobCreateImportJobRequest.parent
CreateKeyRingCreateKeyRingRequest.parent
DecryptDecryptRequest.name
DestroyCryptoKeyVersionDestroyCryptoKeyVersionRequest.name
EncryptEncryptRequest.name
GenerateRandomBytesGenerateRandomBytesRequest.name
GetCryptoKeyGetCryptoKeyRequest.name
GetCryptoKeyVersionGetCryptoKeyVersionRequest.name
GetImportJobGetImportJobRequest.name
GetKeyRingGetKeyRingRequest.name
GetPublicKeyGetPublicKeyRequest.name
ImportCryptoKeyVersionImportCryptoKeyVersionRequest.name
ListCryptoKeyVersionsListCryptoKeyVersionsRequest.parent
ListCryptoKeysListCryptoKeysRequest.parent
ListImportJobsListImportJobsRequest.parent
ListKeyRingsListKeyRingsRequest.parent
MacSignMacSignRequest.name
MacVerifyMacVerifyRequest.name
RawDecryptRawDecryptRequest.name
RawEncryptRawEncryptRequest.name
RestoreCryptoKeyVersionRestoreCryptoKeyVersionRequest.name
UpdateCryptoKeyUpdateCryptoKeyRequest.crypto_key.name
UpdateCryptoKeyPrimaryVersionUpdateCryptoKeyPrimaryVersionRequest.name
UpdateCryptoKeyVersionUpdateCryptoKeyVersionRequest.crypto_key_version.name

Setting the request field

The following examples show where to specify the resource name in variousmethods. Replace the text styled asplace-holder with theactual values used in your Cloud KMS resource IDs.

Decrypt example

If you are making a call toDecrypt, you need to populate the followingfields in your request:

name: 'projects/project-id/locations/location/keyRings/key-ring/cryptoKeys/key-name/'ciphertext: 'iQALWM/r6alAxQm0VQe3...'

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

x-goog-request-params: 'name=projects/project-id/locations/location/keyRings/key-ring/cryptoKeys/key-name/'

CreateKeyRing example

If you are making a call toCreateKeyRing, you need to populate thefollowing fields in your request:

parent: 'projects/project-id/locations/location/'key_ring_id: 'myKeyRing'...

The call metadata also needs to contain theparent resource name:

x-goog-request-params: 'parent=projects/project-id/locations/location/'

UpdateCryptoKey example

If you are making a call toUpdateCryptoKey, you need to populate thefollowing fields in your request:

name: 'projects/project-id/locations/location/keyRings/key-ring/cryptoKeys/key-name/'field_mask: ...

The metadata also needs to contain thename resource name. Note the formatusescrypto_key.name=, notname=:

x-goog-request-params: 'crypto_key.name=projects/project-id/locations/location/keyRings/key-ring/cryptoKeys/key-name/'

Adding metadata using C++

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

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

context.AddMetadata("x-goog-request-params",                    "name=projects/project-id/locations/location/keyRings/key-ring-name/cryptoKeys/key-name/");

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.