secretmanager/v1/service.proto

// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.secretmanager.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/secretmanager/v1/resources.proto";
import "google/iam/v1/iam_policy.proto";
import "google/iam/v1/policy.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.SecretManager.V1";
option go_package = "cloud.google.com/go/secretmanager/apiv1/secretmanagerpb;secretmanagerpb";
option java_multiple_files = true;
option java_outer_classname = "ServiceProto";
option java_package = "com.google.cloud.secretmanager.v1";
option objc_class_prefix = "GSM";
option php_namespace = "Google\\Cloud\\SecretManager\\V1";
option ruby_package = "Google::Cloud::SecretManager::V1";

// Secret Manager Service
//
// Manages secrets and operations using those secrets. Implements a REST
// model with the following objects:
//
// * [Secret][google.cloud.secretmanager.v1.Secret]
// * [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]
service SecretManagerService {
  option (google.api.default_host) = "secretmanager.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Lists [Secrets][google.cloud.secretmanager.v1.Secret].
  rpc ListSecrets(ListSecretsRequest) returns (ListSecretsResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=projects/*}/secrets"
      additional_bindings { get: "/v1/{parent=projects/*/locations/*}/secrets" }
    };
    option (google.api.method_signature) = "parent";
  }

  // Creates a new [Secret][google.cloud.secretmanager.v1.Secret] containing no
  // [SecretVersions][google.cloud.secretmanager.v1.SecretVersion].
  rpc CreateSecret(CreateSecretRequest) returns (Secret) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*}/secrets"
      body: "secret"
      additional_bindings {
        post: "/v1/{parent=projects/*/locations/*}/secrets"
        body: "secret"
      }
    };
    option (google.api.method_signature) = "parent,secret_id,secret";
  }

  // Creates a new [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]
  // containing secret data and attaches it to an existing
  // [Secret][google.cloud.secretmanager.v1.Secret].
  rpc AddSecretVersion(AddSecretVersionRequest) returns (SecretVersion) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*/secrets/*}:addVersion"
      body: "*"
      additional_bindings {
        post: "/v1/{parent=projects/*/locations/*/secrets/*}:addVersion"
        body: "*"
      }
    };
    option (google.api.method_signature) = "parent,payload";
  }

  // Gets metadata for a given [Secret][google.cloud.secretmanager.v1.Secret].
  rpc GetSecret(GetSecretRequest) returns (Secret) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/secrets/*}"
      additional_bindings { get: "/v1/{name=projects/*/locations/*/secrets/*}" }
    };
    option (google.api.method_signature) = "name";
  }

  // Updates metadata of an existing
  // [Secret][google.cloud.secretmanager.v1.Secret].
  rpc UpdateSecret(UpdateSecretRequest) returns (Secret) {
    option (google.api.http) = {
      patch: "/v1/{secret.name=projects/*/secrets/*}"
      body: "secret"
      additional_bindings {
        patch: "/v1/{secret.name=projects/*/locations/*/secrets/*}"
        body: "secret"
      }
    };
    option (google.api.method_signature) = "secret,update_mask";
  }

  // Deletes a [Secret][google.cloud.secretmanager.v1.Secret].
  rpc DeleteSecret(DeleteSecretRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/{name=projects/*/secrets/*}"
      additional_bindings {
        delete: "/v1/{name=projects/*/locations/*/secrets/*}"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Lists [SecretVersions][google.cloud.secretmanager.v1.SecretVersion]. This
  // call does not return secret data.
  rpc ListSecretVersions(ListSecretVersionsRequest)
      returns (ListSecretVersionsResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=projects/*/secrets/*}/versions"
      additional_bindings {
        get: "/v1/{parent=projects/*/locations/*/secrets/*}/versions"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Gets metadata for a
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
  //
  // `projects/*/secrets/*/versions/latest` is an alias to the most recently
  // created [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
  rpc GetSecretVersion(GetSecretVersionRequest) returns (SecretVersion) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/secrets/*/versions/*}"
      additional_bindings {
        get: "/v1/{name=projects/*/locations/*/secrets/*/versions/*}"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Accesses a [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
  // This call returns the secret data.
  //
  // `projects/*/secrets/*/versions/latest` is an alias to the most recently
  // created [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
  rpc AccessSecretVersion(AccessSecretVersionRequest)
      returns (AccessSecretVersionResponse) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/secrets/*/versions/*}:access"
      additional_bindings {
        get: "/v1/{name=projects/*/locations/*/secrets/*/versions/*}:access"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Disables a [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
  //
  // Sets the [state][google.cloud.secretmanager.v1.SecretVersion.state] of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to
  // [DISABLED][google.cloud.secretmanager.v1.SecretVersion.State.DISABLED].
  rpc DisableSecretVersion(DisableSecretVersionRequest)
      returns (SecretVersion) {
    option (google.api.http) = {
      post: "/v1/{name=projects/*/secrets/*/versions/*}:disable"
      body: "*"
      additional_bindings {
        post: "/v1/{name=projects/*/locations/*/secrets/*/versions/*}:disable"
        body: "*"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Enables a [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
  //
  // Sets the [state][google.cloud.secretmanager.v1.SecretVersion.state] of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to
  // [ENABLED][google.cloud.secretmanager.v1.SecretVersion.State.ENABLED].
  rpc EnableSecretVersion(EnableSecretVersionRequest) returns (SecretVersion) {
    option (google.api.http) = {
      post: "/v1/{name=projects/*/secrets/*/versions/*}:enable"
      body: "*"
      additional_bindings {
        post: "/v1/{name=projects/*/locations/*/secrets/*/versions/*}:enable"
        body: "*"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Destroys a [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
  //
  // Sets the [state][google.cloud.secretmanager.v1.SecretVersion.state] of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to
  // [DESTROYED][google.cloud.secretmanager.v1.SecretVersion.State.DESTROYED]
  // and irrevocably destroys the secret data.
  rpc DestroySecretVersion(DestroySecretVersionRequest)
      returns (SecretVersion) {
    option (google.api.http) = {
      post: "/v1/{name=projects/*/secrets/*/versions/*}:destroy"
      body: "*"
      additional_bindings {
        post: "/v1/{name=projects/*/locations/*/secrets/*/versions/*}:destroy"
        body: "*"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Sets the access control policy on the specified secret. Replaces any
  // existing policy.
  //
  // Permissions on
  // [SecretVersions][google.cloud.secretmanager.v1.SecretVersion] are enforced
  // according to the policy set on the associated
  // [Secret][google.cloud.secretmanager.v1.Secret].
  rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest)
      returns (google.iam.v1.Policy) {
    option (google.api.http) = {
      post: "/v1/{resource=projects/*/secrets/*}:setIamPolicy"
      body: "*"
      additional_bindings {
        post: "/v1/{resource=projects/*/locations/*/secrets/*}:setIamPolicy"
        body: "*"
      }
    };
  }

  // Gets the access control policy for a secret.
  // Returns empty policy if the secret exists and does not have a policy set.
  rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest)
      returns (google.iam.v1.Policy) {
    option (google.api.http) = {
      get: "/v1/{resource=projects/*/secrets/*}:getIamPolicy"
      additional_bindings {
        get: "/v1/{resource=projects/*/locations/*/secrets/*}:getIamPolicy"
      }
    };
  }

  // 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.
  rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest)
      returns (google.iam.v1.TestIamPermissionsResponse) {
    option (google.api.http) = {
      post: "/v1/{resource=projects/*/secrets/*}:testIamPermissions"
      body: "*"
      additional_bindings {
        post: "/v1/{resource=projects/*/locations/*/secrets/*}:testIamPermissions"
        body: "*"
      }
    };
  }
}

// Request message for
// [SecretManagerService.ListSecrets][google.cloud.secretmanager.v1.SecretManagerService.ListSecrets].
message ListSecretsRequest {
  // Required. The resource name of the project associated with the
  // [Secrets][google.cloud.secretmanager.v1.Secret], in the format `projects/*`
  // or `projects/*/locations/*`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "secretmanager.googleapis.com/Secret"
    }
  ];

  // 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.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Pagination token, returned earlier via
  // [ListSecretsResponse.next_page_token][google.cloud.secretmanager.v1.ListSecretsResponse.next_page_token].
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Filter string, adhering to the rules in
  // [List-operation
  // filtering](https://cloud.google.com/secret-manager/docs/filtering). List
  // only secrets matching the filter. If filter is empty, all secrets are
  // listed.
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [SecretManagerService.ListSecrets][google.cloud.secretmanager.v1.SecretManagerService.ListSecrets].
message ListSecretsResponse {
  // The list of [Secrets][google.cloud.secretmanager.v1.Secret] sorted in
  // reverse by create_time (newest first).
  repeated Secret secrets = 1;

  // A token to retrieve the next page of results. Pass this value in
  // [ListSecretsRequest.page_token][google.cloud.secretmanager.v1.ListSecretsRequest.page_token]
  // to retrieve the next page.
  string next_page_token = 2;

  // The total number of [Secrets][google.cloud.secretmanager.v1.Secret] but 0
  // when the
  // [ListSecretsRequest.filter][google.cloud.secretmanager.v1.ListSecretsRequest.filter]
  // field is set.
  int32 total_size = 3;
}

// Request message for
// [SecretManagerService.CreateSecret][google.cloud.secretmanager.v1.SecretManagerService.CreateSecret].
message CreateSecretRequest {
  // Required. The resource name of the project to associate with the
  // [Secret][google.cloud.secretmanager.v1.Secret], in the format `projects/*`
  // or `projects/*/locations/*`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "secretmanager.googleapis.com/Secret"
    }
  ];

  // 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.
  string secret_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. A [Secret][google.cloud.secretmanager.v1.Secret] with initial
  // field values.
  Secret secret = 3 [(google.api.field_behavior) = REQUIRED];
}

// Request message for
// [SecretManagerService.AddSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.AddSecretVersion].
message AddSecretVersionRequest {
  // Required. The resource name of the
  // [Secret][google.cloud.secretmanager.v1.Secret] to associate with the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] in the format
  // `projects/*/secrets/*` or `projects/*/locations/*/secrets/*`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/Secret"
    }
  ];

  // Required. The secret payload of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion].
  SecretPayload payload = 2 [(google.api.field_behavior) = REQUIRED];
}

// Request message for
// [SecretManagerService.GetSecret][google.cloud.secretmanager.v1.SecretManagerService.GetSecret].
message GetSecretRequest {
  // Required. The resource name of the
  // [Secret][google.cloud.secretmanager.v1.Secret], in the format
  // `projects/*/secrets/*` or `projects/*/locations/*/secrets/*`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/Secret"
    }
  ];
}

// Request message for
// [SecretManagerService.ListSecretVersions][google.cloud.secretmanager.v1.SecretManagerService.ListSecretVersions].
message ListSecretVersionsRequest {
  // Required. The resource name of the
  // [Secret][google.cloud.secretmanager.v1.Secret] associated with the
  // [SecretVersions][google.cloud.secretmanager.v1.SecretVersion] to list, in
  // the format `projects/*/secrets/*` or `projects/*/locations/*/secrets/*`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/Secret"
    }
  ];

  // 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.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Pagination token, returned earlier via
  // ListSecretVersionsResponse.next_page_token][].
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Filter string, adhering to the rules in
  // [List-operation
  // filtering](https://cloud.google.com/secret-manager/docs/filtering). List
  // only secret versions matching the filter. If filter is empty, all secret
  // versions are listed.
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [SecretManagerService.ListSecretVersions][google.cloud.secretmanager.v1.SecretManagerService.ListSecretVersions].
message ListSecretVersionsResponse {
  // The list of [SecretVersions][google.cloud.secretmanager.v1.SecretVersion]
  // sorted in reverse by create_time (newest first).
  repeated SecretVersion versions = 1;

  // A token to retrieve the next page of results. Pass this value in
  // [ListSecretVersionsRequest.page_token][google.cloud.secretmanager.v1.ListSecretVersionsRequest.page_token]
  // to retrieve the next page.
  string next_page_token = 2;

  // The total number of
  // [SecretVersions][google.cloud.secretmanager.v1.SecretVersion] but 0 when
  // the
  // [ListSecretsRequest.filter][google.cloud.secretmanager.v1.ListSecretsRequest.filter]
  // field is set.
  int32 total_size = 3;
}

// Request message for
// [SecretManagerService.GetSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.GetSecretVersion].
message GetSecretVersionRequest {
  // Required. The resource name of the
  // [SecretVersion][google.cloud.secretmanager.v1.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][google.cloud.secretmanager.v1.SecretVersion].
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/SecretVersion"
    }
  ];
}

// Request message for
// [SecretManagerService.UpdateSecret][google.cloud.secretmanager.v1.SecretManagerService.UpdateSecret].
message UpdateSecretRequest {
  // Required. [Secret][google.cloud.secretmanager.v1.Secret] with updated field
  // values.
  Secret secret = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. Specifies the fields to be updated.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = REQUIRED];
}

// Request message for
// [SecretManagerService.AccessSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.AccessSecretVersion].
message AccessSecretVersionRequest {
  // Required. The resource name of the
  // [SecretVersion][google.cloud.secretmanager.v1.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][google.cloud.secretmanager.v1.SecretVersion].
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/SecretVersion"
    }
  ];
}

// Response message for
// [SecretManagerService.AccessSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.AccessSecretVersion].
message AccessSecretVersionResponse {
  // The resource name of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] in the format
  // `projects/*/secrets/*/versions/*` or
  // `projects/*/locations/*/secrets/*/versions/*`.
  string name = 1 [(google.api.resource_reference) = {
    type: "secretmanager.googleapis.com/SecretVersion"
  }];

  // Secret payload
  SecretPayload payload = 2;
}

// Request message for
// [SecretManagerService.DeleteSecret][google.cloud.secretmanager.v1.SecretManagerService.DeleteSecret].
message DeleteSecretRequest {
  // Required. The resource name of the
  // [Secret][google.cloud.secretmanager.v1.Secret] to delete in the format
  // `projects/*/secrets/*`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/Secret"
    }
  ];

  // Optional. Etag of the [Secret][google.cloud.secretmanager.v1.Secret]. The
  // request succeeds if it matches the etag of the currently stored secret
  // object. If the etag is omitted, the request succeeds.
  string etag = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for
// [SecretManagerService.DisableSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.DisableSecretVersion].
message DisableSecretVersionRequest {
  // Required. The resource name of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to disable in
  // the format `projects/*/secrets/*/versions/*` or
  // `projects/*/locations/*/secrets/*/versions/*`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/SecretVersion"
    }
  ];

  // Optional. Etag of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]. The request
  // succeeds if it matches the etag of the currently stored secret version
  // object. If the etag is omitted, the request succeeds.
  string etag = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for
// [SecretManagerService.EnableSecretVersion][google.cloud.secretmanager.v1.SecretManagerService.EnableSecretVersion].
message EnableSecretVersionRequest {
  // Required. The resource name of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to enable in
  // the format `projects/*/secrets/*/versions/*` or
  // `projects/*/locations/*/secrets/*/versions/*`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/SecretVersion"
    }
  ];

  // Optional. Etag of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]. The request
  // succeeds if it matches the etag of the currently stored secret version
  // object. If the etag is omitted, the request succeeds.
  string etag = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for
// [SecretManagerService.DestroySecretVersion][google.cloud.secretmanager.v1.SecretManagerService.DestroySecretVersion].
message DestroySecretVersionRequest {
  // Required. The resource name of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion] to destroy in
  // the format `projects/*/secrets/*/versions/*` or
  // `projects/*/locations/*/secrets/*/versions/*`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "secretmanager.googleapis.com/SecretVersion"
    }
  ];

  // Optional. Etag of the
  // [SecretVersion][google.cloud.secretmanager.v1.SecretVersion]. The request
  // succeeds if it matches the etag of the currently stored secret version
  // object. If the etag is omitted, the request succeeds.
  string etag = 2 [(google.api.field_behavior) = OPTIONAL];
}