1// Copyright 2021 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.secretmanager.v1;
18
19import "google/api/annotations.proto";
20import "google/api/client.proto";
21import "google/api/field_behavior.proto";
22import "google/api/resource.proto";
23import "google/cloud/secretmanager/v1/resources.proto";
24import "google/iam/v1/iam_policy.proto";
25import "google/iam/v1/policy.proto";
26import "google/protobuf/empty.proto";
27import "google/protobuf/field_mask.proto";
28
29option cc_enable_arenas = true;
30option csharp_namespace = "Google.Cloud.SecretManager.V1";
31option go_package = "cloud.google.com/go/secretmanager/apiv1/secretmanagerpb;secretmanagerpb";
32option java_multiple_files = true;
33option java_outer_classname = "ServiceProto";
34option java_package = "com.google.cloud.secretmanager.v1";
35option objc_class_prefix = "GSM";
36option php_namespace = "Google\\Cloud\\SecretManager\\V1";
37option ruby_package = "Google::Cloud::SecretManager::V1";
38
39// Secret Manager Service
40//
41// Manages secrets and operations using those secrets. Implements a REST
42// model with the following objects:
43//
44// * [Secret][google.cloud.secretmanager.v1.Secret]
45// * [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]
46service SecretManagerService {
47  option (google.api.default_host) = "secretmanager.googleapis.com";
48  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
49
50  // Lists [Secrets][google.cloud.secretmanager.v1.Secret].
51  rpc ListSecrets(ListSecretsRequest) returns (ListSecretsResponse) {
52    option (google.api.http) = {
53      get: "/v1/{parent=projects/*}/secrets"
54    };
55    option (google.api.method_signature) = "parent";
56  }
57
58  // Creates a new [Secret][google.cloud.secretmanager.v1.Secret] containing no [SecretVersions][google.cloud.secretmanager.v1.SecretVersion].
59  rpc CreateSecret(CreateSecretRequest) returns (Secret) {
60    option (google.api.http) = {
61      post: "/v1/{parent=projects/*}/secrets"
62      body: "secret"
63    };
64    option (google.api.method_signature) = "parent,secret_id,secret";
65  }
66
67  // Creates a new [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] containing secret data and attaches
68  // it to an existing [Secret][google.cloud.secretmanager.v1.Secret].
69  rpc AddSecretVersion(AddSecretVersionRequest) returns (SecretVersion) {
70    option (google.api.http) = {
71      post: "/v1/{parent=projects/*/secrets/*}:addVersion"
72      body: "*"
73    };
74    option (google.api.method_signature) = "parent,payload";
75  }
76
77  // Gets metadata for a given [Secret][google.cloud.secretmanager.v1.Secret].
78  rpc GetSecret(GetSecretRequest) returns (Secret) {
79    option (google.api.http) = {
80      get: "/v1/{name=projects/*/secrets/*}"
81    };
82    option (google.api.method_signature) = "name";
83  }
84
85  // Updates metadata of an existing [Secret][google.cloud.secretmanager.v1.Secret].
86  rpc UpdateSecret(UpdateSecretRequest) returns (Secret) {
87    option (google.api.http) = {
88      patch: "/v1/{secret.name=projects/*/secrets/*}"
89      body: "secret"
90    };
91    option (google.api.method_signature) = "secret,update_mask";
92  }
93
94  // Deletes a [Secret][google.cloud.secretmanager.v1.Secret].
95  rpc DeleteSecret(DeleteSecretRequest) returns (google.protobuf.Empty) {
96    option (google.api.http) = {
97      delete: "/v1/{name=projects/*/secrets/*}"
98    };
99    option (google.api.method_signature) = "name";
100  }
101
102  // Lists [SecretVersions][google.cloud.secretmanager.v1.SecretVersion]. This call does not return secret
103  // data.
104  rpc ListSecretVersions(ListSecretVersionsRequest) returns (ListSecretVersionsResponse) {
105    option (google.api.http) = {
106      get: "/v1/{parent=projects/*/secrets/*}/versions"
107    };
108    option (google.api.method_signature) = "parent";
109  }
110
111  // Gets metadata for a [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
112  //
113  // `projects/*/secrets/*/versions/latest` is an alias to the most recently
114  // created [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
115  rpc GetSecretVersion(GetSecretVersionRequest) returns (SecretVersion) {
116    option (google.api.http) = {
117      get: "/v1/{name=projects/*/secrets/*/versions/*}"
118    };
119    option (google.api.method_signature) = "name";
120  }
121
122  // Accesses a [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]. This call returns the secret data.
123  //
124  // `projects/*/secrets/*/versions/latest` is an alias to the most recently
125  // created [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
126  rpc AccessSecretVersion(AccessSecretVersionRequest) returns (AccessSecretVersionResponse) {
127    option (google.api.http) = {
128      get: "/v1/{name=projects/*/secrets/*/versions/*}:access"
129    };
130    option (google.api.method_signature) = "name";
131  }
132
133  // Disables a [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
134  //
135  // Sets the [state][google.cloud.secretmanager.v1.SecretVersion.state] of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to
136  // [DISABLED][google.cloud.secretmanager.v1.SecretVersion.State.DISABLED].
137  rpc DisableSecretVersion(DisableSecretVersionRequest) returns (SecretVersion) {
138    option (google.api.http) = {
139      post: "/v1/{name=projects/*/secrets/*/versions/*}:disable"
140      body: "*"
141    };
142    option (google.api.method_signature) = "name";
143  }
144
145  // Enables a [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
146  //
147  // Sets the [state][google.cloud.secretmanager.v1.SecretVersion.state] of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to
148  // [ENABLED][google.cloud.secretmanager.v1.SecretVersion.State.ENABLED].
149  rpc EnableSecretVersion(EnableSecretVersionRequest) returns (SecretVersion) {
150    option (google.api.http) = {
151      post: "/v1/{name=projects/*/secrets/*/versions/*}:enable"
152      body: "*"
153    };
154    option (google.api.method_signature) = "name";
155  }
156
157  // Destroys a [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
158  //
159  // Sets the [state][google.cloud.secretmanager.v1.SecretVersion.state] of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to
160  // [DESTROYED][google.cloud.secretmanager.v1.SecretVersion.State.DESTROYED] and irrevocably destroys the
161  // secret data.
162  rpc DestroySecretVersion(DestroySecretVersionRequest) returns (SecretVersion) {
163    option (google.api.http) = {
164      post: "/v1/{name=projects/*/secrets/*/versions/*}:destroy"
165      body: "*"
166    };
167    option (google.api.method_signature) = "name";
168  }
169
170  // Sets the access control policy on the specified secret. Replaces any
171  // existing policy.
172  //
173  // Permissions on [SecretVersions][google.cloud.secretmanager.v1.SecretVersion] are enforced according
174  // to the policy set on the associated [Secret][google.cloud.secretmanager.v1.Secret].
175  rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) {
176    option (google.api.http) = {
177      post: "/v1/{resource=projects/*/secrets/*}:setIamPolicy"
178      body: "*"
179    };
180  }
181
182  // Gets the access control policy for a secret.
183  // Returns empty policy if the secret exists and does not have a policy set.
184  rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) {
185    option (google.api.http) = {
186      get: "/v1/{resource=projects/*/secrets/*}:getIamPolicy"
187    };
188  }
189
190  // Returns permissions that a caller has for the specified secret.
191  // If the secret does not exist, this call returns an empty set of
192  // permissions, not a NOT_FOUND error.
193  //
194  // Note: This operation is designed to be used for building permission-aware
195  // UIs and command-line tools, not for authorization checking. This operation
196  // may "fail open" without warning.
197  rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) {
198    option (google.api.http) = {
199      post: "/v1/{resource=projects/*/secrets/*}:testIamPermissions"
200      body: "*"
201    };
202  }
203}
204
205// Request message for [SecretManagerService.ListSecrets][google.cloud.secretmanager.v1.SecretManagerService.ListSecrets].
206message ListSecretsRequest {
207  // Required. The resource name of the project associated with the
208  // [Secrets][google.cloud.secretmanager.v1.Secret], in the format `projects/*`.
209  string parent = 1 [
210    (google.api.field_behavior) = REQUIRED,
211    (google.api.resource_reference) = {
212      type: "cloudresourcemanager.googleapis.com/Project"
213    }
214  ];
215
216  // Optional. The maximum number of results to be returned in a single page. If
217  // set to 0, the server decides the number of results to return. If the
218  // number is greater than 25000, it is capped at 25000.
219  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
220
221  // Optional. Pagination token, returned earlier via
222  // [ListSecretsResponse.next_page_token][google.cloud.secretmanager.v1.ListSecretsResponse.next_page_token].
223  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
224
225  // Optional. Filter string, adhering to the rules in
226  // [List-operation
227  // filtering](https://cloud.google.com/secret-manager/docs/filtering). List
228  // only secrets matching the filter. If filter is empty, all secrets are
229  // listed.
230  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
231}
232
233// Response message for [SecretManagerService.ListSecrets][google.cloud.secretmanager.v1.SecretManagerService.ListSecrets].
234message ListSecretsResponse {
235  // The list of [Secrets][google.cloud.secretmanager.v1.Secret] sorted in reverse by create_time (newest
236  // first).
237  repeated Secret secrets = 1;
238
239  // A token to retrieve the next page of results. Pass this value in
240  // [ListSecretsRequest.page_token][google.cloud.secretmanager.v1.ListSecretsRequest.page_token] to retrieve the next page.
241  string next_page_token = 2;
242
243  // The total number of [Secrets][google.cloud.secretmanager.v1.Secret].
244  int32 total_size = 3;
245}
246
247// Request message for [SecretManagerService.CreateSecret][google.cloud.secretmanager.v1.SecretManagerService.CreateSecret].
248message CreateSecretRequest {
249  // Required. The resource name of the project to associate with the
250  // [Secret][google.cloud.secretmanager.v1.Secret], in the format `projects/*`.
251  string parent = 1 [
252    (google.api.field_behavior) = REQUIRED,
253    (google.api.resource_reference) = {
254      type: "cloudresourcemanager.googleapis.com/Project"
255    }
256  ];
257
258  // Required. This must be unique within the project.
259  //
260  // A secret ID is a string with a maximum length of 255 characters and can
261  // contain uppercase and lowercase letters, numerals, and the hyphen (`-`) and
262  // underscore (`_`) characters.
263  string secret_id = 2 [(google.api.field_behavior) = REQUIRED];
264
265  // Required. A [Secret][google.cloud.secretmanager.v1.Secret] with initial field values.
266  Secret secret = 3 [(google.api.field_behavior) = REQUIRED];
267}
268
269// Request message for [SecretManagerService.AddSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.AddSecretVersion].
270message AddSecretVersionRequest {
271  // Required. The resource name of the [Secret][google.cloud.secretmanager.v1.Secret] to associate with the
272  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] in the format `projects/*/secrets/*`.
273  string parent = 1 [
274    (google.api.field_behavior) = REQUIRED,
275    (google.api.resource_reference) = {
276      type: "secretmanager.googleapis.com/Secret"
277    }
278  ];
279
280  // Required. The secret payload of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
281  SecretPayload payload = 2 [(google.api.field_behavior) = REQUIRED];
282}
283
284// Request message for [SecretManagerService.GetSecret][google.cloud.secretmanager.v1.SecretManagerService.GetSecret].
285message GetSecretRequest {
286  // Required. The resource name of the [Secret][google.cloud.secretmanager.v1.Secret], in the format `projects/*/secrets/*`.
287  string name = 1 [
288    (google.api.field_behavior) = REQUIRED,
289    (google.api.resource_reference) = {
290      type: "secretmanager.googleapis.com/Secret"
291    }
292  ];
293}
294
295// Request message for [SecretManagerService.ListSecretVersions][google.cloud.secretmanager.v1.SecretManagerService.ListSecretVersions].
296message ListSecretVersionsRequest {
297  // Required. The resource name of the [Secret][google.cloud.secretmanager.v1.Secret] associated with the
298  // [SecretVersions][google.cloud.secretmanager.v1.SecretVersion] to list, in the format
299  // `projects/*/secrets/*`.
300  string parent = 1 [
301    (google.api.field_behavior) = REQUIRED,
302    (google.api.resource_reference) = {
303      type: "secretmanager.googleapis.com/Secret"
304    }
305  ];
306
307  // Optional. The maximum number of results to be returned in a single page. If
308  // set to 0, the server decides the number of results to return. If the
309  // number is greater than 25000, it is capped at 25000.
310  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
311
312  // Optional. Pagination token, returned earlier via
313  // ListSecretVersionsResponse.next_page_token][].
314  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
315
316  // Optional. Filter string, adhering to the rules in
317  // [List-operation
318  // filtering](https://cloud.google.com/secret-manager/docs/filtering). List
319  // only secret versions matching the filter. If filter is empty, all secret
320  // versions are listed.
321  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
322}
323
324// Response message for [SecretManagerService.ListSecretVersions][google.cloud.secretmanager.v1.SecretManagerService.ListSecretVersions].
325message ListSecretVersionsResponse {
326  // The list of [SecretVersions][google.cloud.secretmanager.v1.SecretVersion] sorted in reverse by
327  // create_time (newest first).
328  repeated SecretVersion versions = 1;
329
330  // A token to retrieve the next page of results. Pass this value in
331  // [ListSecretVersionsRequest.page_token][google.cloud.secretmanager.v1.ListSecretVersionsRequest.page_token] to retrieve the next page.
332  string next_page_token = 2;
333
334  // The total number of [SecretVersions][google.cloud.secretmanager.v1.SecretVersion].
335  int32 total_size = 3;
336}
337
338// Request message for [SecretManagerService.GetSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.GetSecretVersion].
339message GetSecretVersionRequest {
340  // Required. The resource name of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] in the format
341  // `projects/*/secrets/*/versions/*`.
342  //
343  // `projects/*/secrets/*/versions/latest` is an alias to the most recently
344  // created [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
345  string name = 1 [
346    (google.api.field_behavior) = REQUIRED,
347    (google.api.resource_reference) = {
348      type: "secretmanager.googleapis.com/SecretVersion"
349    }
350  ];
351}
352
353// Request message for [SecretManagerService.UpdateSecret][google.cloud.secretmanager.v1.SecretManagerService.UpdateSecret].
354message UpdateSecretRequest {
355  // Required. [Secret][google.cloud.secretmanager.v1.Secret] with updated field values.
356  Secret secret = 1 [(google.api.field_behavior) = REQUIRED];
357
358  // Required. Specifies the fields to be updated.
359  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
360}
361
362// Request message for [SecretManagerService.AccessSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.AccessSecretVersion].
363message AccessSecretVersionRequest {
364  // Required. The resource name of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] in the format
365  // `projects/*/secrets/*/versions/*`.
366  //
367  // `projects/*/secrets/*/versions/latest` is an alias to the most recently
368  // created [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
369  string name = 1 [
370    (google.api.field_behavior) = REQUIRED,
371    (google.api.resource_reference) = {
372      type: "secretmanager.googleapis.com/SecretVersion"
373    }
374  ];
375}
376
377// Response message for [SecretManagerService.AccessSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.AccessSecretVersion].
378message AccessSecretVersionResponse {
379  // The resource name of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] in the format
380  // `projects/*/secrets/*/versions/*`.
381  string name = 1 [(google.api.resource_reference) = {
382                     type: "secretmanager.googleapis.com/SecretVersion"
383                   }];
384
385  // Secret payload
386  SecretPayload payload = 2;
387}
388
389// Request message for [SecretManagerService.DeleteSecret][google.cloud.secretmanager.v1.SecretManagerService.DeleteSecret].
390message DeleteSecretRequest {
391  // Required. The resource name of the [Secret][google.cloud.secretmanager.v1.Secret] to delete in the format
392  // `projects/*/secrets/*`.
393  string name = 1 [
394    (google.api.field_behavior) = REQUIRED,
395    (google.api.resource_reference) = {
396      type: "secretmanager.googleapis.com/Secret"
397    }
398  ];
399
400  // Optional. Etag of the [Secret][google.cloud.secretmanager.v1.Secret]. The request succeeds if it matches
401  // the etag of the currently stored secret object. If the etag is omitted,
402  // the request succeeds.
403  string etag = 2 [(google.api.field_behavior) = OPTIONAL];
404}
405
406// Request message for [SecretManagerService.DisableSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.DisableSecretVersion].
407message DisableSecretVersionRequest {
408  // Required. The resource name of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to disable in the format
409  // `projects/*/secrets/*/versions/*`.
410  string name = 1 [
411    (google.api.field_behavior) = REQUIRED,
412    (google.api.resource_reference) = {
413      type: "secretmanager.googleapis.com/SecretVersion"
414    }
415  ];
416
417  // Optional. Etag of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]. The request succeeds if it matches
418  // the etag of the currently stored secret version object. If the etag is
419  // omitted, the request succeeds.
420  string etag = 2 [(google.api.field_behavior) = OPTIONAL];
421}
422
423// Request message for [SecretManagerService.EnableSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.EnableSecretVersion].
424message EnableSecretVersionRequest {
425  // Required. The resource name of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to enable in the format
426  // `projects/*/secrets/*/versions/*`.
427  string name = 1 [
428    (google.api.field_behavior) = REQUIRED,
429    (google.api.resource_reference) = {
430      type: "secretmanager.googleapis.com/SecretVersion"
431    }
432  ];
433
434  // Optional. Etag of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]. The request succeeds if it matches
435  // the etag of the currently stored secret version object. If the etag is
436  // omitted, the request succeeds.
437  string etag = 2 [(google.api.field_behavior) = OPTIONAL];
438}
439
440// Request message for [SecretManagerService.DestroySecretVersion][google.cloud.secretmanager.v1.SecretManagerService.DestroySecretVersion].
441message DestroySecretVersionRequest {
442  // Required. The resource name of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to destroy in the format
443  // `projects/*/secrets/*/versions/*`.
444  string name = 1 [
445    (google.api.field_behavior) = REQUIRED,
446    (google.api.resource_reference) = {
447      type: "secretmanager.googleapis.com/SecretVersion"
448    }
449  ];
450
451  // Optional. Etag of the [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]. The request succeeds if it matches
452  // the etag of the currently stored secret version object. If the etag is
453  // omitted, the request succeeds.
454  string etag = 2 [(google.api.field_behavior) = OPTIONAL];
455}
456