0
# Secret Version Management
1

2
Management of secret versions and access to secret data. Secret versions contain the actual secret data and can be in different states (enabled, disabled, destroyed). Each secret can have multiple versions, allowing for secret rotation and rollback capabilities.
3

4
## Capabilities
5

6
### Adding Secret Versions
7

8
Creates a new version of an existing secret with the provided secret data. New versions are automatically enabled and become the latest version.
9

10
```python { .api }
11
def add_secret_version(self, request: AddSecretVersionRequest = None, **kwargs) -> SecretVersion:
12
    """
13
    Creates a new SecretVersion containing secret data and attaches it to an existing Secret.
14

15
    Args:
16
        request (AddSecretVersionRequest): The request object.
17
        parent (str): Required. The resource name of the Secret to associate with the
18
            SecretVersion in the format projects/*/secrets/*.
19
        payload (SecretPayload): Required. The secret payload containing the secret data.
20

21
    Returns:
22
        SecretVersion: The created SecretVersion.
23

24
    Raises:
25
        google.api_core.exceptions.NotFound: If the parent secret does not exist.
26
        google.api_core.exceptions.InvalidArgument: If payload is invalid.
27
        google.api_core.exceptions.PermissionDenied: If insufficient permissions.
28
    """
29
```
30

31
**Usage Example:**
32

33
```python
34
from google.cloud import secretmanager
35

36
client = secretmanager.SecretManagerServiceClient()
37

38
# Create payload with secret data
39
payload = secretmanager.SecretPayload()
40
payload.data = b"new-api-key-v2"
41

42
# Add version to existing secret
43
request = secretmanager.AddSecretVersionRequest()
44
request.parent = "projects/my-project/secrets/api-key"
45
request.payload = payload
46

47
version = client.add_secret_version(request=request)
48
print(f"Created version: {version.name}")
49
print(f"State: {version.state}")
50
```
51

52
### Retrieving Secret Version Metadata
53

54
Gets metadata for a specific secret version without accessing the secret data. Returns version state, creation time, and other metadata.
55

56
```python { .api }
57
def get_secret_version(self, request: GetSecretVersionRequest = None, **kwargs) -> SecretVersion:
58
    """
59
    Gets metadata for a given SecretVersion.
60

61
    Args:
62
        request (GetSecretVersionRequest): The request object.
63
        name (str): Required. The resource name of the SecretVersion in the format
64
            projects/*/secrets/*/versions/* or projects/*/secrets/*/versions/latest.
65

66
    Returns:
67
        SecretVersion: The SecretVersion metadata.
68

69
    Raises:
70
        google.api_core.exceptions.NotFound: If the secret version does not exist.
71
        google.api_core.exceptions.PermissionDenied: If insufficient permissions.
72
    """
73
```
74

75
**Usage Example:**
76

77
```python
78
# Get specific version
79
request = secretmanager.GetSecretVersionRequest()
80
request.name = "projects/my-project/secrets/api-key/versions/1"
81

82
version = client.get_secret_version(request=request)
83
print(f"Version state: {version.state}")
84
print(f"Created: {version.create_time}")
85

86
# Get latest version
87
request.name = "projects/my-project/secrets/api-key/versions/latest"
88
latest_version = client.get_secret_version(request=request)
89
print(f"Latest version: {latest_version.name}")
90
```
91

92
### Accessing Secret Data
93

94
Retrieves the actual secret data from a secret version. This is the primary method for reading secret values.
95

96
```python { .api }
97
def access_secret_version(self, request: AccessSecretVersionRequest = None, **kwargs) -> AccessSecretVersionResponse:
98
    """
99
    Accesses a SecretVersion containing the secret data.
100

101
    Args:
102
        request (AccessSecretVersionRequest): The request object.
103
        name (str): Required. The resource name of the SecretVersion in the format
104
            projects/*/secrets/*/versions/* or projects/*/secrets/*/versions/latest.
105

106
    Returns:
107
        AccessSecretVersionResponse: Response containing the secret payload.
108

109
    Raises:
110
        google.api_core.exceptions.NotFound: If the secret version does not exist.
111
        google.api_core.exceptions.PermissionDenied: If insufficient permissions.
112
        google.api_core.exceptions.FailedPrecondition: If version is disabled or destroyed.
113
    """
114
```
115

116
**Usage Example:**
117

118
```python
119
# Access latest version data
120
request = secretmanager.AccessSecretVersionRequest()
121
request.name = "projects/my-project/secrets/api-key/versions/latest"
122

123
response = client.access_secret_version(request=request)
124
secret_data = response.payload.data.decode('utf-8')
125
print(f"Secret value: {secret_data}")
126

127
# Access specific version
128
request.name = "projects/my-project/secrets/api-key/versions/1"
129
response = client.access_secret_version(request=request)
130
print(f"Version 1 data: {response.payload.data}")
131

132
# Check data integrity with CRC32C
133
if response.payload.data_crc32c:
134
    import crc32c
135
    computed_crc = crc32c.crc32c(response.payload.data)
136
    if computed_crc != response.payload.data_crc32c:
137
        raise ValueError("Data integrity check failed")
138
```
139

140
### Listing Secret Versions
141

142
Lists all versions of a secret with optional filtering and pagination. Returns version metadata without accessing secret data.
143

144
```python { .api }
145
def list_secret_versions(self, request: ListSecretVersionsRequest = None, **kwargs) -> ListSecretVersionsPager:
146
    """
147
    Lists SecretVersions.
148

149
    Args:
150
        request (ListSecretVersionsRequest): The request object.
151
        parent (str): Required. The resource name of the Secret associated with the
152
            SecretVersions to list, in the format projects/*/secrets/*.
153
        page_size (int): Optional. The maximum number of results to return in a single page.
154
        page_token (str): Optional. Pagination token.
155
        filter (str): Optional. Filter string adhering to the filtering rules.
156

157
    Returns:
158
        ListSecretVersionsPager: An iterator for paginated results.
159

160
    Raises:
161
        google.api_core.exceptions.NotFound: If the parent secret does not exist.
162
        google.api_core.exceptions.InvalidArgument: If filter is malformed.
163
        google.api_core.exceptions.PermissionDenied: If insufficient permissions.
164
    """
165
```
166

167
**Usage Example:**
168

169
```python
170
# List all versions
171
request = secretmanager.ListSecretVersionsRequest()
172
request.parent = "projects/my-project/secrets/api-key"
173

174
for version in client.list_secret_versions(request=request):
175
    print(f"Version: {version.name}")
176
    print(f"  State: {version.state}")
177
    print(f"  Created: {version.create_time}")
178

179
# List only enabled versions
180
request.filter = 'state="ENABLED"'
181
enabled_versions = list(client.list_secret_versions(request=request))
182
print(f"Enabled versions: {len(enabled_versions)}")
183
```
184

185
### Enabling Secret Versions
186

187
Enables a disabled secret version, making it accessible for reading secret data.
188

189
```python { .api }
190
def enable_secret_version(self, request: EnableSecretVersionRequest = None, **kwargs) -> SecretVersion:
191
    """
192
    Enables a SecretVersion.
193

194
    Args:
195
        request (EnableSecretVersionRequest): The request object.
196
        name (str): Required. The resource name of the SecretVersion to enable in the
197
            format projects/*/secrets/*/versions/*.
198
        etag (str): Optional. Etag for optimistic concurrency control.
199

200
    Returns:
201
        SecretVersion: The enabled SecretVersion.
202

203
    Raises:
204
        google.api_core.exceptions.NotFound: If the secret version does not exist.
205
        google.api_core.exceptions.FailedPrecondition: If version is destroyed.
206
        google.api_core.exceptions.PermissionDenied: If insufficient permissions.
207
    """
208
```
209

210
**Usage Example:**
211

212
```python
213
request = secretmanager.EnableSecretVersionRequest()
214
request.name = "projects/my-project/secrets/api-key/versions/1"
215

216
version = client.enable_secret_version(request=request)
217
print(f"Enabled version: {version.name}")
218
print(f"New state: {version.state}")
219
```
220

221
### Disabling Secret Versions
222

223
Disables a secret version, preventing access to its secret data while preserving the version for potential re-enabling.
224

225
```python { .api }
226
def disable_secret_version(self, request: DisableSecretVersionRequest = None, **kwargs) -> SecretVersion:
227
    """
228
    Disables a SecretVersion.
229

230
    Args:
231
        request (DisableSecretVersionRequest): The request object.
232
        name (str): Required. The resource name of the SecretVersion to disable in the
233
            format projects/*/secrets/*/versions/*.
234
        etag (str): Optional. Etag for optimistic concurrency control.
235

236
    Returns:
237
        SecretVersion: The disabled SecretVersion.
238

239
    Raises:
240
        google.api_core.exceptions.NotFound: If the secret version does not exist.
241
        google.api_core.exceptions.FailedPrecondition: If version is destroyed.
242
        google.api_core.exceptions.PermissionDenied: If insufficient permissions.
243
    """
244
```
245

246
**Usage Example:**
247

248
```python
249
request = secretmanager.DisableSecretVersionRequest()
250
request.name = "projects/my-project/secrets/api-key/versions/1"
251

252
version = client.disable_secret_version(request=request)
253
print(f"Disabled version: {version.name}")
254
print(f"New state: {version.state}")
255
```
256

257
### Destroying Secret Versions
258

259
Permanently destroys a secret version and its data. This operation cannot be undone and immediately makes the version data inaccessible.
260

261
```python { .api }
262
def destroy_secret_version(self, request: DestroySecretVersionRequest = None, **kwargs) -> SecretVersion:
263
    """
264
    Destroys a SecretVersion.
265

266
    Args:
267
        request (DestroySecretVersionRequest): The request object.
268
        name (str): Required. The resource name of the SecretVersion to destroy in the
269
            format projects/*/secrets/*/versions/*.
270
        etag (str): Optional. Etag for optimistic concurrency control.
271

272
    Returns:
273
        SecretVersion: The destroyed SecretVersion.
274

275
    Raises:
276
        google.api_core.exceptions.NotFound: If the secret version does not exist.
277
        google.api_core.exceptions.PermissionDenied: If insufficient permissions.
278
    """
279
```
280

281
**Usage Example:**
282

283
```python
284
request = secretmanager.DestroySecretVersionRequest()
285
request.name = "projects/my-project/secrets/old-api-key/versions/1"
286

287
version = client.destroy_secret_version(request=request)
288
print(f"Destroyed version: {version.name}")
289
print(f"State: {version.state}")
290
print(f"Destroy time: {version.destroy_time}")
291
```
292

293
## Path Helper Methods
294

295
```python { .api }
296
@staticmethod
297
def secret_version_path(project: str, secret: str, secret_version: str) -> str:
298
    """Returns a fully-qualified secret version string."""
299

300
@staticmethod
301
def parse_secret_version_path(path: str) -> Dict[str, str]:
302
    """Parses a secret version path into its component segments."""
303
```
304

305
**Usage Example:**
306

307
```python
308
# Construct version path
309
version_path = client.secret_version_path("my-project", "api-key", "1")
310
print(version_path)  # "projects/my-project/secrets/api-key/versions/1"
311

312
# Parse version path
313
components = client.parse_secret_version_path(version_path)
314
print(components)  # {'project': 'my-project', 'secret': 'api-key', 'secret_version': '1'}
315
```
316

317
## Request Types
318

319
### AddSecretVersionRequest
320

321
```python { .api }
322
class AddSecretVersionRequest:
323
    """
324
    Request message for SecretManagerService.AddSecretVersion.
325
    
326
    Attributes:
327
        parent (str): Required. The secret resource name.
328
        payload (SecretPayload): Required. The secret data.
329
    """
330
    parent: str
331
    payload: SecretPayload
332
```
333

334
### GetSecretVersionRequest
335

336
```python { .api }
337
class GetSecretVersionRequest:
338
    """
339
    Request message for SecretManagerService.GetSecretVersion.
340
    
341
    Attributes:
342
        name (str): Required. The secret version resource name.
343
    """
344
    name: str
345
```
346

347
### AccessSecretVersionRequest
348

349
```python { .api }
350
class AccessSecretVersionRequest:
351
    """
352
    Request message for SecretManagerService.AccessSecretVersion.
353
    
354
    Attributes:
355
        name (str): Required. The secret version resource name.
356
    """
357
    name: str
358
```
359

360
### AccessSecretVersionResponse
361

362
```python { .api }
363
class AccessSecretVersionResponse:
364
    """
365
    Response message for SecretManagerService.AccessSecretVersion.
366
    
367
    Attributes:
368
        name (str): The secret version resource name.
369
        payload (SecretPayload): The secret payload.
370
    """
371
    name: str
372
    payload: SecretPayload
373
```
374

375
### ListSecretVersionsRequest
376

377
```python { .api }
378
class ListSecretVersionsRequest:
379
    """
380
    Request message for SecretManagerService.ListSecretVersions.
381
    
382
    Attributes:
383
        parent (str): Required. The secret resource name.
384
        page_size (int): Optional. Maximum results per page.
385
        page_token (str): Optional. Pagination token.
386
        filter (str): Optional. Filter expression.
387
    """
388
    parent: str
389
    page_size: int
390
    page_token: str
391
    filter: str
392
```
393

394
### ListSecretVersionsResponse
395

396
```python { .api }
397
class ListSecretVersionsResponse:
398
    """
399
    Response message for SecretManagerService.ListSecretVersions.
400
    
401
    Attributes:
402
        versions (Sequence[SecretVersion]): List of secret versions.
403
        next_page_token (str): Token for next page.
404
        total_size (int): Total number of versions.
405
    """
406
    versions: Sequence[SecretVersion]
407
    next_page_token: str
408
    total_size: int
409
```
410

411
### EnableSecretVersionRequest
412

413
```python { .api }
414
class EnableSecretVersionRequest:
415
    """
416
    Request message for SecretManagerService.EnableSecretVersion.
417
    
418
    Attributes:
419
        name (str): Required. The secret version resource name.
420
        etag (str): Optional. Etag for optimistic concurrency control.
421
    """
422
    name: str
423
    etag: str
424
```
425

426
### DisableSecretVersionRequest
427

428
```python { .api }
429
class DisableSecretVersionRequest:
430
    """
431
    Request message for SecretManagerService.DisableSecretVersion.
432
    
433
    Attributes:
434
        name (str): Required. The secret version resource name.
435
        etag (str): Optional. Etag for optimistic concurrency control.
436
    """
437
    name: str
438
    etag: str
439
```
440

441
### DestroySecretVersionRequest
442

443
```python { .api }
444
class DestroySecretVersionRequest:
445
    """
446
    Request message for SecretManagerService.DestroySecretVersion.
447
    
448
    Attributes:
449
        name (str): Required. The secret version resource name.
450
        etag (str): Optional. Etag for optimistic concurrency control.
451
    """
452
    name: str
453
    etag: str
454
```