0
# Google Cloud Secret Manager
1

2
Google Cloud Secret Manager API client library for Python that stores, manages, and secures access to application secrets. This comprehensive client provides both synchronous and asynchronous APIs for creating, storing, accessing, and managing secrets and their versions with built-in IAM integration, encryption options, and audit capabilities.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-secret-manager
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-secret-manager`
9

10
## Core Imports
11

12
```python
13
from google.cloud import secretmanager
14
```
15

16
Specific client imports:
17

18
```python
19
from google.cloud.secretmanager import SecretManagerServiceClient
20
from google.cloud.secretmanager import SecretManagerServiceAsyncClient
21
```
22

23
Type imports:
24

25
```python
26
from google.cloud.secretmanager import Secret, SecretVersion, SecretPayload
27
from google.cloud.secretmanager import CreateSecretRequest, AddSecretVersionRequest
28
from google.cloud.secretmanager import Replication, CustomerManagedEncryption
29
from google.cloud.secretmanager import Topic, Rotation
30
```
31

32
Advanced imports for enterprise features:
33

34
```python
35
# For IAM operations
36
from google.iam.v1 import iam_policy_pb2, policy_pb2
37

38
# For async operations
39
from google.cloud.secretmanager import SecretManagerServiceAsyncClient
40

41
# For pagination
42
from google.cloud.secretmanager import ListSecretsPager, ListSecretsAsyncPager
43

44
# For location operations
45
from google.cloud.location import locations_pb2
46

47
# For field masks (updates)
48
from google.protobuf import field_mask_pb2
49
```
50

51
## Basic Usage
52

53
```python
54
from google.cloud import secretmanager
55

56
# Initialize the client
57
client = secretmanager.SecretManagerServiceClient()
58

59
# Project path
60
project_id = "your-project-id"
61
parent = f"projects/{project_id}"
62

63
# Create a secret
64
secret_id = "my-secret"
65
secret = secretmanager.Secret()
66
secret.replication = secretmanager.Replication()
67
secret.replication.automatic = secretmanager.Replication.Automatic()
68

69
create_secret_request = secretmanager.CreateSecretRequest()
70
create_secret_request.parent = parent
71
create_secret_request.secret_id = secret_id
72
create_secret_request.secret = secret
73

74
response = client.create_secret(request=create_secret_request)
75
print(f"Created secret: {response.name}")
76

77
# Add a secret version with data
78
secret_name = response.name
79
payload = secretmanager.SecretPayload()
80
payload.data = b"my-secret-data"
81

82
add_version_request = secretmanager.AddSecretVersionRequest()
83
add_version_request.parent = secret_name
84
add_version_request.payload = payload
85

86
version_response = client.add_secret_version(request=add_version_request)
87
print(f"Added secret version: {version_response.name}")
88

89
# Access the secret data
90
access_request = secretmanager.AccessSecretVersionRequest()
91
access_request.name = version_response.name
92

93
access_response = client.access_secret_version(request=access_request)
94
data = access_response.payload.data.decode('utf-8')
95
print(f"Secret data: {data}")
96
```
97

98
## Architecture
99

100
Google Cloud Secret Manager client follows Google API design patterns:
101

102
- **Client Classes**: Synchronous (`SecretManagerServiceClient`) and asynchronous (`SecretManagerServiceAsyncClient`) clients providing identical APIs
103
- **Request/Response Pattern**: All API operations use structured request objects and return response objects
104
- **Resource Hierarchy**: Secrets belong to projects, secret versions belong to secrets
105
- **Transport Layer**: Supports gRPC and REST protocols with automatic retries and authentication
106
- **Type Safety**: Proto-based message types ensure type safety and schema validation
107

108
## Capabilities
109

110
### Secret Management
111

112
Core secret lifecycle operations including creating secrets with replication policies, retrieving secret metadata, updating configurations, and deleting secrets. Provides complete CRUD operations for secret resources.
113

114
```python { .api }
115
def create_secret(self, request: CreateSecretRequest = None, **kwargs) -> Secret: ...
116
def get_secret(self, request: GetSecretRequest = None, **kwargs) -> Secret: ...
117
def update_secret(self, request: UpdateSecretRequest = None, **kwargs) -> Secret: ...
118
def delete_secret(self, request: DeleteSecretRequest = None, **kwargs) -> None: ...
119
def list_secrets(self, request: ListSecretsRequest = None, **kwargs) -> ListSecretsPager: ...
120
```
121

122
[Secret Management](./secret-management.md)
123

124
### Secret Version Management
125

126
Managing secret versions and accessing secret data, including adding new versions, retrieving version metadata, accessing secret payloads, and controlling version lifecycle states (enabled/disabled/destroyed).
127

128
```python { .api }
129
def add_secret_version(self, request: AddSecretVersionRequest = None, **kwargs) -> SecretVersion: ...
130
def get_secret_version(self, request: GetSecretVersionRequest = None, **kwargs) -> SecretVersion: ...
131
def access_secret_version(self, request: AccessSecretVersionRequest = None, **kwargs) -> AccessSecretVersionResponse: ...
132
def list_secret_versions(self, request: ListSecretVersionsRequest = None, **kwargs) -> ListSecretVersionsPager: ...
133
def enable_secret_version(self, request: EnableSecretVersionRequest = None, **kwargs) -> SecretVersion: ...
134
def disable_secret_version(self, request: DisableSecretVersionRequest = None, **kwargs) -> SecretVersion: ...
135
def destroy_secret_version(self, request: DestroySecretVersionRequest = None, **kwargs) -> SecretVersion: ...
136
```
137

138
[Secret Version Management](./secret-version-management.md)
139

140
### IAM and Security
141

142
Identity and Access Management operations for controlling access to secrets, including setting IAM policies, retrieving current policies, and testing permissions. Provides fine-grained access control integration.
143

144
```python { .api }
145
def set_iam_policy(self, request: SetIamPolicyRequest = None, **kwargs) -> Policy: ...
146
def get_iam_policy(self, request: GetIamPolicyRequest = None, **kwargs) -> Policy: ...
147
def test_iam_permissions(self, request: TestIamPermissionsRequest = None, **kwargs) -> TestIamPermissionsResponse: ...
148
```
149

150
[IAM and Security](./iam-security.md)
151

152
### Data Types and Models
153

154
Core data structures including Secret, SecretVersion, SecretPayload, replication configurations, encryption settings, and all request/response types used throughout the API.
155

156
```python { .api }
157
class Secret: ...
158
class SecretVersion: ...
159
class SecretPayload: ...
160
class Replication: ...
161
class CustomerManagedEncryption: ...
162
```
163

164
[Data Types and Models](./data-types.md)
165

166
## Error Handling
167

168
The client uses Google API Core exceptions:
169

170
```python
171
from google.api_core import exceptions
172

173
try:
174
    secret = client.get_secret(request=get_request)
175
except exceptions.NotFound:
176
    print("Secret not found")
177
except exceptions.PermissionDenied:
178
    print("Access denied")
179
except exceptions.InvalidArgument as e:
180
    print(f"Invalid argument: {e}")
181
```
182

183
## Async Usage
184

185
```python
186
import asyncio
187
from google.cloud.secretmanager import SecretManagerServiceAsyncClient
188

189
async def manage_secrets():
190
    async with SecretManagerServiceAsyncClient() as client:
191
        # All methods are async versions of synchronous client
192
        secrets = []
193
        async for secret in await client.list_secrets(request=list_request):
194
            secrets.append(secret)
195
        return secrets
196

197
# Run async function
198
secrets = asyncio.run(manage_secrets())
199
```