REST Resource: projects.locations.secrets

Resource: 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.

JSON representation
{
  "name": string,
  "replication": {
    object (Replication)
  },
  "createTime": string,
  "labels": {
    string: string,
    ...
  },
  "topics": [
    {
      object (Topic)
    }
  ],
  "etag": string,
  "rotation": {
    object (Rotation)
  },
  "versionAliases": {
    string: string,
    ...
  },
  "annotations": {
    string: string,
    ...
  },
  "versionDestroyTtl": string,
  "customerManagedEncryption": {
    object (CustomerManagedEncryption)
  },
  "tags": {
    string: string,
    ...
  },
  "secretType": enum (SecretType),
  "policyMember": {
    object (ResourcePolicyMember)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "expireTime": string,
  "ttl": string
  // End of mutually exclusive fields.
}
Fields
name

string

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

replication

object (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.

createTime

string (Timestamp format)

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

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

labels

map (key: string, value: 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.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

topics[]

object (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

object (Rotation)

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

versionAliases

map (key: string, value: string (int64 format))

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 secrets.get and modifiable via secrets.patch. Access by alias is only be supported on versions.get and versions.access.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

annotations

map (key: string, value: 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.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

versionDestroyTtl

string (Duration format)

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.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

customerManagedEncryption

object (CustomerManagedEncryption)

Optional. The customer-managed encryption configuration of the regionalized secrets. If no configuration is provided, Google Cloud-powered encryption key is used.

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

tags

map (key: string, value: string)

Optional. Input only. Immutable. Mapping of Tag keys/values directly bound to this resource. For example: "123/environment": "production", "123/costCenter": "marketing"

Tags are used to organize and group resources.

Tags can be used to control policy evaluation for the resource.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

secretType

enum (SecretType)

Optional. Immutable. This defines the type of the secret. Enforces certain structural requirements on the SecretVersions. For secret of type UNSPECIFIED, the SecretVersions can be of any type.

policyMember

object (ResourcePolicyMember)

Output only. Defines the policy member for the secret. This will be used to check if the caller has the permission to perform certain operations on the typed secret.

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. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:

expireTime

string (Timestamp format)

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

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

ttl

string (Duration format)

Input only. The TTL for the Secret.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

End of mutually exclusive fields.

Replication

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

JSON representation
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "automatic": {
    object (Automatic)
  },
  "userManaged": {
    object (UserManaged)
  }
  // End of mutually exclusive fields.
}
Fields
The replication policy for this secret. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
automatic

object (Automatic)

The Secret will automatically be replicated without any restrictions.

userManaged

object (UserManaged)

The Secret will only be replicated into the locations specified.

End of mutually exclusive fields.

Automatic

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

JSON representation
{
  "customerManagedEncryption": {
    object (CustomerManagedEncryption)
  }
}
Fields
customerManagedEncryption

object (CustomerManagedEncryption)

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

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

CustomerManagedEncryption

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

JSON representation
{
  "kmsKeyName": string
}
Fields
kmsKeyName

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/*.

UserManaged

A replication policy that replicates the Secret payload into the locations specified in Replication.UserManaged.replicas

JSON representation
{
  "replicas": [
    {
      object (Replica)
    }
  ]
}
Fields
replicas[]

object (Replica)

Required. The list of Replicas for this Secret.

Cannot be empty.

Replica

Represents a Replica for this Secret.

JSON representation
{
  "location": string,
  "customerManagedEncryption": {
    object (CustomerManagedEncryption)
  }
}
Fields
location

string

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

customerManagedEncryption

object (CustomerManagedEncryption)

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

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

Topic

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

JSON representation
{
  "name": string
}
Fields
name

string

Identifier. 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.

Rotation

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

JSON representation
{
  "nextRotationTime": string,
  "rotationPeriod": string,
  "managedRotationStatus": {
    object (ManagedRotationStatus)
  }
}
Fields
nextRotationTime

string (Timestamp format)

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).

nextRotationTime MUST be set if rotationPeriod is set.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

rotationPeriod

string (Duration format)

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

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

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

managedRotationStatus

object (ManagedRotationStatus)

Output only. The current status of the managed rotation. This field is only applicable to Typed Secrets. This field is set by the service and cannot be set by the user.

ManagedRotationStatus

Represents the status of a managed rotation.

This is applicable only to Typed Secrets. It indicates whether the rotation is active and any errors that may have occurred during the asynchronous managed rotation.

JSON representation
{
  "state": enum (State),
  "error": {
    object (Status)
  }
}
Fields
state

enum (State)

Output only. Indicates whether the Managed Rotation is active or not.

error

object (Status)

Output only. Displays customer-facing issues that occurred during an asynchronous managed rotation. For example, if there are some permission errors.

State

This defines the various states in which the managed rotation can be.

Enums
STATE_UNSPECIFIED Not specified. This value is unused and invalid.
ACTIVE Indicates that the Managed rotation is ACTIVE.
INACTIVE Indicates that the Managed rotation is INACTIVE.

Status

The Status type defines a logical different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data:

You can find out more about this [API Design Guide](https://documentation.s3ns.fr/apis/design/

JSON representation
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Fields
code

integer

The status code, which should be an enum value of google.rpc.Code.

message

string

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.

details[]

object

A list of messages that carry the error details. There is a common set of message types for APIs to use.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

SecretType

This defines the various values of the type of secret can be.

Enums
SECRET_TYPE_UNSPECIFIED Applicable to all secrets which do not have any restriction on the SecretVersions.
CLOUD_SQL_DB_CREDENTIALS Applicable to secrets which are used for the managed rotation feature for Cloud SQL Single User.
ACCESS_KEY Applicable to secrets where the payload contains an access key.
CERTIFICATE Applicable to secrets where the payload contains a certificate.
OTHER_DB_CREDENTIALS Applicable to secrets where the payload contains database credentials.
OTHER Applicable to secrets whose type doesn't belong to any of the above defined types.

ResourcePolicyMember

Output-only policy member strings of a Cloud de Confiance resource's built-in identity.

JSON representation
{
  "iamPolicyNamePrincipal": string,
  "iamPolicyUidPrincipal": string
}
Fields
iamPolicyNamePrincipal

string

Output only. IAM policy binding member referring to a Cloud de Confiance resource by user-assigned name (https://google.aip.dev//122). If a resource is deleted and recreated with the same name, the binding will be applicable to the new resource.

Example: principal://parametermanager.googleapis.com/projects/12345/name/locations/us-central1-a/parameters/my-parameter

iamPolicyUidPrincipal

string

Output only. IAM policy binding member referring to a Cloud de Confiance resource by system-assigned unique identifier (https://google.aip.dev//148#uid). If a resource is deleted and recreated with the same name, the binding will not be applicable to the new resource

Example: principal://parametermanager.googleapis.com/projects/12345/uid/locations/us-central1-a/parameters/a918fed5

Methods

addVersion

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

create

Creates a new Secret containing no SecretVersions.

delete

Deletes a Secret.

get

Gets metadata for a given Secret.

getIamPolicy

Gets the access control policy for a secret.

list

Lists Secrets.

patch

Updates metadata of an existing Secret.

setIamPolicy

Sets the access control policy on the specified secret.

testIamPermissions

Returns permissions that a caller has for the specified secret.

enableManagedRotation

The method google.cloud.secretmanager.v1.SecretManagerService.EnableManagedRotation is not available in Cloud de Confiance by S3NS.

rotateSecret

The method google.cloud.secretmanager.v1.SecretManagerService.RotateSecret is not available in Cloud de Confiance by S3NS.