Package google.cloud.secretmanager.v1

Index

SecretManagerService

Secret Manager Service

Manages secrets and operations using those secrets. Implements a REST model with the following objects:

AccessSecretVersion

rpc AccessSecretVersion(AccessSecretVersionRequest) returns (AccessSecretVersionResponse)

Accesses a SecretVersion. This call returns the secret data.

projects/*/secrets/*/versions/latest is an alias to the most recently created SecretVersion.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
AddSecretVersion

rpc AddSecretVersion(AddSecretVersionRequest) returns (SecretVersion)

Creates a new SecretVersion containing secret data and attaches it to an existing Secret.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
CreateSecret

rpc CreateSecret(CreateSecretRequest) returns (Secret)

Creates a new Secret containing no SecretVersions.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DeleteSecret

rpc DeleteSecret(DeleteSecretRequest) returns (Empty)

Deletes a Secret.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DestroySecretVersion

rpc DestroySecretVersion(DestroySecretVersionRequest) returns (SecretVersion)

Destroys a SecretVersion.

Sets the state of the SecretVersion to DESTROYED and irrevocably destroys the secret data.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
DisableSecretVersion

rpc DisableSecretVersion(DisableSecretVersionRequest) returns (SecretVersion)

Disables a SecretVersion.

Sets the state of the SecretVersion to DISABLED.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
EnableSecretVersion

rpc EnableSecretVersion(EnableSecretVersionRequest) returns (SecretVersion)

Enables a SecretVersion.

Sets the state of the SecretVersion to ENABLED.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetIamPolicy

rpc GetIamPolicy(GetIamPolicyRequest) returns (Policy)

Gets the access control policy for a secret. Returns empty policy if the secret exists and does not have a policy set.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetSecret

rpc GetSecret(GetSecretRequest) returns (Secret)

Gets metadata for a given Secret.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
GetSecretVersion

rpc GetSecretVersion(GetSecretVersionRequest) returns (SecretVersion)

Gets metadata for a SecretVersion.

projects/*/secrets/*/versions/latest is an alias to the most recently created SecretVersion.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListSecretVersions

rpc ListSecretVersions(ListSecretVersionsRequest) returns (ListSecretVersionsResponse)

Lists SecretVersions. This call does not return secret data.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
ListSecrets

rpc ListSecrets(ListSecretsRequest) returns (ListSecretsResponse)

Lists Secrets.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
SetIamPolicy

rpc SetIamPolicy(SetIamPolicyRequest) returns (Policy)

Sets the access control policy on the specified secret. Replaces any existing policy.

Permissions on SecretVersions are enforced according to the policy set on the associated Secret.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
TestIamPermissions

rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse)

Returns permissions that a caller has for the specified secret. If the secret does not exist, this call returns an empty set of permissions, not a NOT_FOUND error.

Note: This operation is designed to be used for building permission-aware UIs and command-line tools, not for authorization checking. This operation may "fail open" without warning.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.
UpdateSecret

rpc UpdateSecret(UpdateSecretRequest) returns (Secret)

Updates metadata of an existing Secret.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

AccessSecretVersionRequest

Request message for SecretManagerService.AccessSecretVersion.

Fields
name

string

Required. The resource name of the SecretVersion in the format projects/*/secrets/*/versions/* or projects/*/locations/*/secrets/*/versions/*.

projects/*/secrets/*/versions/latest or projects/*/locations/*/secrets/*/versions/latest is an alias to the most recently created SecretVersion.

Authorization requires the following IAM permission on the specified resource name:

  • secretmanager.versions.access

AccessSecretVersionResponse

Response message for SecretManagerService.AccessSecretVersion.

Fields
name

string

The resource name of the SecretVersion in the format projects/*/secrets/*/versions/* or projects/*/locations/*/secrets/*/versions/*.
payload

SecretPayload

Secret payload

AddSecretVersionRequest

Request message for SecretManagerService.AddSecretVersion.

Fields
parent

string

Required. The resource name of the Secret to associate with the SecretVersion in the format projects/*/secrets/* or projects/*/locations/*/secrets/*.

Authorization requires the following IAM permission on the specified resource parent:

  • secretmanager.versions.add
payload

SecretPayload

Required. The secret payload of the SecretVersion.

CreateSecretRequest

Request message for SecretManagerService.CreateSecret.

Fields
parent

string

Required. The resource name of the project to associate with the Secret, in the format projects/* or projects/*/locations/*.

Authorization requires the following IAM permission on the specified resource parent:

  • secretmanager.secrets.create
secret_id

string

Required. This must be unique within the project.

A secret ID is a string with a maximum length of 255 characters and can contain uppercase and lowercase letters, numerals, and the hyphen (-) and underscore (_) characters.
secret

Secret

Required. A Secret with initial field values.

CustomerManagedEncryption

Configuration for encrypting secret payloads using customer-managed encryption keys (CMEK).

Fields
kms_key_name

string

Required. The resource name of the Cloud KMS CryptoKey used to encrypt secret payloads.

For secrets using the UserManaged replication policy type, Cloud KMS CryptoKeys must reside in the same location as the [replica location][Secret.UserManaged.Replica.location].

For secrets using the Automatic replication policy type, Cloud KMS CryptoKeys must reside in global.

The expected format is projects/*/locations/*/keyRings/*/cryptoKeys/*.

CustomerManagedEncryptionStatus

Describes the status of customer-managed encryption.

Fields
kms_key_version_name

string

Required. The resource name of the Cloud KMS CryptoKeyVersion used to encrypt the secret payload, in the following format: projects/*/locations/*/keyRings/*/cryptoKeys/*/versions/*.

DeleteSecretRequest

Request message for SecretManagerService.DeleteSecret.

Fields
name

string

Required. The resource name of the Secret to delete in the format projects/*/secrets/*.

Authorization requires the following IAM permission on the specified resource name:

  • secretmanager.secrets.delete
etag

string

Optional. Etag of the Secret. The request succeeds if it matches the etag of the currently stored secret object. If the etag is omitted, the request succeeds.

DestroySecretVersionRequest

Request message for SecretManagerService.DestroySecretVersion.

Fields
name

string

Required. The resource name of the SecretVersion to destroy in the format projects/*/secrets/*/versions/* or projects/*/locations/*/secrets/*/versions/*.

Authorization requires the following IAM permission on the specified resource name:

  • secretmanager.versions.destroy
etag

string

Optional. Etag of the SecretVersion. The request succeeds if it matches the etag of the currently stored secret version object. If the etag is omitted, the request succeeds.

DisableSecretVersionRequest

Request message for SecretManagerService.DisableSecretVersion.

Fields
name

string

Required. The resource name of the SecretVersion to disable in the format projects/*/secrets/*/versions/* or projects/*/locations/*/secrets/*/versions/*.

Authorization requires the following IAM permission on the specified resource name:

  • secretmanager.secrets.disable
etag

string

Optional. Etag of the SecretVersion. The request succeeds if it matches the etag of the currently stored secret version object. If the etag is omitted, the request succeeds.

EnableSecretVersionRequest

Request message for SecretManagerService.EnableSecretVersion.

Fields
name

string

Required. The resource name of the SecretVersion to enable in the format projects/*/secrets/*/versions/* or projects/*/locations/*/secrets/*/versions/*.

Authorization requires the following IAM permission on the specified resource name:

  • secretmanager.secrets.enable
etag

string

Optional. Etag of the SecretVersion. The request succeeds if it matches the etag of the currently stored secret version object. If the etag is omitted, the request succeeds.

GetSecretRequest

Request message for SecretManagerService.GetSecret.

Fields
name

string

Required. The resource name of the Secret, in the format projects/*/secrets/* or projects/*/locations/*/secrets/*.

Authorization requires the following IAM permission on the specified resource name:

  • secretmanager.secrets.get

GetSecretVersionRequest

Request message for SecretManagerService.GetSecretVersion.

Fields
name

string

Required. The resource name of the SecretVersion in the format projects/*/secrets/*/versions/* or projects/*/locations/*/secrets/*/versions/*.

projects/*/secrets/*/versions/latest or projects/*/locations/*/secrets/*/versions/latest is an alias to the most recently created SecretVersion.

Authorization requires the following IAM permission on the specified resource name:

  • secretmanager.versions.get

ListSecretVersionsRequest

Request message for SecretManagerService.ListSecretVersions.

Fields
parent

string

Required. The resource name of the Secret associated with the SecretVersions to list, in the format projects/*/secrets/* or projects/*/locations/*/secrets/*.

Authorization requires the following IAM permission on the specified resource parent:

  • secretmanager.versions.list
page_size

int32

Optional. The maximum number of results to be returned in a single page. If set to 0, the server decides the number of results to return. If the number is greater than 25000, it is capped at 25000.
page_token

string

Optional. Pagination token, returned earlier via ListSecretVersionsResponse.next_page_token][].
filter

string

Optional. Filter string, adhering to the rules in List-operation filtering. List only secret versions matching the filter. If filter is empty, all secret versions are listed.

ListSecretVersionsResponse

Response message for SecretManagerService.ListSecretVersions.

Fields
versions[]

SecretVersion

The list of SecretVersions sorted in reverse by create_time (newest first).
next_page_token

string

A token to retrieve the next page of results. Pass this value in ListSecretVersionsRequest.page_token to retrieve the next page.
total_size

int32

The total number of SecretVersions but 0 when the ListSecretsRequest.filter field is set.

ListSecretsRequest

Request message for SecretManagerService.ListSecrets.

Fields
parent

string

Required. The resource name of the project associated with the Secrets, in the format projects/* or projects/*/locations/*

Authorization requires the following IAM permission on the specified resource parent:

  • secretmanager.secrets.list
page_size

int32

Optional. The maximum number of results to be returned in a single page. If set to 0, the server decides the number of results to return. If the number is greater than 25000, it is capped at 25000.
page_token

string

Optional. Pagination token, returned earlier via ListSecretsResponse.next_page_token.
filter

string

Optional. Filter string, adhering to the rules in List-operation filtering. List only secrets matching the filter. If filter is empty, all secrets are listed.

ListSecretsResponse

Response message for SecretManagerService.ListSecrets.

Fields
secrets[]

Secret

The list of Secrets sorted in reverse by create_time (newest first).
next_page_token

string

A token to retrieve the next page of results. Pass this value in ListSecretsRequest.page_token to retrieve the next page.
total_size

int32

The total number of Secrets but 0 when the ListSecretsRequest.filter field is set.

Replication

A policy that defines the replication and encryption configuration of data.

Fields
Union field replication. The replication policy for this secret. replication can be only one of the following:
automatic

Automatic

The Secret will automatically be replicated without any restrictions.
user_managed

UserManaged

The Secret will only be replicated into the locations specified.

Automatic

A replication policy that replicates the Secret payload without any restrictions.

Fields
customer_managed_encryption

CustomerManagedEncryption

Optional. The customer-managed encryption configuration of the Secret. If no configuration is provided, Google-managed default encryption is used.

Updates to the Secret encryption configuration only apply to SecretVersions added afterwards. They do not apply retroactively to existing SecretVersions.

UserManaged

A replication policy that replicates the Secret payload into the locations specified in [Secret.replication.user_managed.replicas][]

Fields
replicas[]

Replica

Required. The list of Replicas for this Secret.

Cannot be empty.

Replica

Represents a Replica for this Secret.

Fields
location

string

The canonical IDs of the location to replicate data. For example: "us-east1".
customer_managed_encryption

CustomerManagedEncryption

Optional. The customer-managed encryption configuration of the [User-Managed Replica][Replication.UserManaged.Replica]. If no configuration is provided, Google-managed default encryption is used.

Updates to the Secret encryption configuration only apply to SecretVersions added afterwards. They do not apply retroactively to existing SecretVersions.

ReplicationStatus

The replication status of a SecretVersion.

Fields
Union field replication_status. The replication status of the SecretVersion. replication_status can be only one of the following:
automatic

AutomaticStatus

Describes the replication status of a SecretVersion with automatic replication.

Only populated if the parent Secret has an automatic replication policy.
user_managed

UserManagedStatus

Describes the replication status of a SecretVersion with user-managed replication.

Only populated if the parent Secret has a user-managed replication policy.

AutomaticStatus

The replication status of a SecretVersion using automatic replication.

Only populated if the parent Secret has an automatic replication policy.

Fields
customer_managed_encryption

CustomerManagedEncryptionStatus

Output only. The customer-managed encryption status of the SecretVersion. Only populated if customer-managed encryption is used.

UserManagedStatus

The replication status of a SecretVersion using user-managed replication.

Only populated if the parent Secret has a user-managed replication policy.

Fields
replicas[]

ReplicaStatus

Output only. The list of replica statuses for the SecretVersion.

ReplicaStatus

Describes the status of a user-managed replica for the SecretVersion.

Fields
location

string

Output only. The canonical ID of the replica location. For example: "us-east1".
customer_managed_encryption

CustomerManagedEncryptionStatus

Output only. The customer-managed encryption status of the SecretVersion. Only populated if customer-managed encryption is used.

Rotation

The rotation time and period for a Secret. At next_rotation_time, Secret Manager will send a Pub/Sub notification to the topics configured on the Secret. Secret.topics must be set to configure rotation.

Fields
next_rotation_time

Timestamp

Optional. Timestamp in UTC at which the Secret is scheduled to rotate. Cannot be set to less than 300s (5 min) in the future and at most 3153600000s (100 years).

next_rotation_time MUST be set if rotation_period is set.
rotation_period

Duration

Input only. The Duration between rotation notifications. Must be in seconds and at least 3600s (1h) and at most 3153600000s (100 years).

If rotation_period is set, next_rotation_time must be set. next_rotation_time will be advanced by this period when the service automatically sends rotation notifications.

Secret

A Secret is a logical secret whose value and versions can be accessed.

A Secret is made up of zero or more SecretVersions that represent the secret data.

Fields
name

string

Output only. The resource name of the Secret in the format projects/*/secrets/*.
replication

Replication

Optional. Immutable. The replication policy of the secret data attached to the Secret.

The replication policy cannot be changed after the Secret has been created.
create_time

Timestamp

Output only. The time at which the Secret was created.
labels

map<string, string>

The labels assigned to this Secret.

Label keys must be between 1 and 63 characters long, have a UTF-8 encoding of maximum 128 bytes, and must conform to the following PCRE regular expression: [\p{Ll}\p{Lo}][\p{Ll}\p{Lo}\p{N}_-]{0,62}

Label values must be between 0 and 63 characters long, have a UTF-8 encoding of maximum 128 bytes, and must conform to the following PCRE regular expression: [\p{Ll}\p{Lo}\p{N}_-]{0,63}

No more than 64 labels can be assigned to a given resource.
topics[]

Topic

Optional. A list of up to 10 Pub/Sub topics to which messages are published when control plane operations are called on the secret or its versions.
etag

string

Optional. Etag of the currently stored Secret.
rotation

Rotation

Optional. Rotation policy attached to the Secret. May be excluded if there is no rotation policy.
version_aliases

map<string, int64>

Optional. Mapping from version alias to version name.

A version alias is a string with a maximum length of 63 characters and can contain uppercase and lowercase letters, numerals, and the hyphen (-) and underscore ('_') characters. An alias string must start with a letter and cannot be the string 'latest' or 'NEW'. No more than 50 aliases can be assigned to a given secret.

Version-Alias pairs will be viewable via GetSecret and modifiable via UpdateSecret. Access by alias is only be supported on GetSecretVersion and AccessSecretVersion.
annotations

map<string, string>

Optional. Custom metadata about the secret.

Annotations are distinct from various forms of labels. Annotations exist to allow client tools to store their own state information without requiring a database.

Annotation keys must be between 1 and 63 characters long, have a UTF-8 encoding of maximum 128 bytes, begin and end with an alphanumeric character ([a-z0-9A-Z]), and may have dashes (-), underscores (_), dots (.), and alphanumerics in between these symbols.

The total size of annotation keys and values must be less than 16KiB.
version_destroy_ttl

Duration

Optional. Secret Version TTL after destruction request

This is a part of the Delayed secret version destroy feature. For secret with TTL>0, version destruction doesn't happen immediately on calling destroy instead the version goes to a disabled state and destruction happens after the TTL expires.
customer_managed_encryption

CustomerManagedEncryption

Optional. The customer-managed encryption configuration of the Regionalised Secrets. If no configuration is provided, Google-managed default encryption is used.

Updates to the Secret encryption configuration only apply to SecretVersions added afterwards. They do not apply retroactively to existing SecretVersions.

Union field expiration. Expiration policy attached to the Secret. If specified the Secret and all SecretVersions will be automatically deleted at expiration. Expired secrets are irreversibly deleted.

Expiration is not the recommended way to set time-based permissions. IAM Conditions is recommended for granting time-based permissions because the operation can be reversed. expiration can be only one of the following:
expire_time

Timestamp

Optional. Timestamp in UTC when the Secret is scheduled to expire. This is always provided on output, regardless of what was sent on input.
ttl

Duration

Input only. The TTL for the Secret.

SecretPayload

A secret payload resource in the Secret Manager API. This contains the sensitive secret payload that is associated with a SecretVersion.

Fields
data

bytes

The secret data. Must be no larger than 64KiB.
data_crc32c

int64

Optional. If specified, SecretManagerService will verify the integrity of the received data on SecretManagerService.AddSecretVersion calls using the crc32c checksum and store it to include in future SecretManagerService.AccessSecretVersion responses. If a checksum is not provided in the SecretManagerService.AddSecretVersion request, the SecretManagerService will generate and store one for you.

The CRC32C value is encoded as a Int64 for compatibility, and can be safely downconverted to uint32 in languages that support this type. https://cloud.google.com/apis/design/design_patterns#integer_types

SecretVersion

A secret version resource in the Secret Manager API.

Fields
name

string

Output only. The resource name of the SecretVersion in the format projects/*/secrets/*/versions/*.

SecretVersion IDs in a Secret start at 1 and are incremented for each subsequent version of the secret.
create_time

Timestamp

Output only. The time at which the SecretVersion was created.
destroy_time

Timestamp

Output only. The time this SecretVersion was destroyed. Only present if state is DESTROYED.
state

State

Output only. The current state of the SecretVersion.
replication_status

ReplicationStatus

The replication status of the SecretVersion.
etag

string

Output only. Etag of the currently stored SecretVersion.
client_specified_payload_checksum

bool

Output only. True if payload checksum specified in SecretPayload object has been received by SecretManagerService on SecretManagerService.AddSecretVersion.
scheduled_destroy_time

Timestamp

Optional. Output only. Scheduled destroy time for secret version. This is a part of the Delayed secret version destroy feature. For a Secret with a valid version destroy TTL, when a secert version is destroyed, version is moved to disabled state and it is scheduled for destruction Version is destroyed only after the scheduled_destroy_time.
customer_managed_encryption

CustomerManagedEncryptionStatus

Output only. The customer-managed encryption status of the SecretVersion. Only populated if customer-managed encryption is used and Secret is a Regionalised Secret.

State

The state of a SecretVersion, indicating if it can be accessed.

Enums
STATE_UNSPECIFIED Not specified. This value is unused and invalid.
ENABLED The SecretVersion may be accessed.
DISABLED The SecretVersion may not be accessed, but the secret data is still available and can be placed back into the ENABLED state.
DESTROYED The SecretVersion is destroyed and the secret data is no longer stored. A version may not leave this state once entered.

Topic

A Pub/Sub topic which Secret Manager will publish to when control plane events occur on this secret.

Fields
name

string

Required. The resource name of the Pub/Sub topic that will be published to, in the following format: projects/*/topics/*. For publication to succeed, the Secret Manager service agent must have the pubsub.topic.publish permission on the topic. The Pub/Sub Publisher role (roles/pubsub.publisher) includes this permission.

UpdateSecretRequest

Request message for SecretManagerService.UpdateSecret.

Fields
secret

Secret

Required. Secret with updated field values.

Authorization requires the following IAM permission on the specified resource secret:

  • secretmanager.secrets.update
update_mask

FieldMask

Required. Specifies the fields to be updated.