temporalio · mastermanu · Jun 3, 2025
@@ -0,0 +1,20 @@
+name: Push to Buf Registry
+
+on:
+  push:
+    tags:
+      - 'v**'
+    branches:
+      - main
+permissions:
+  contents: read
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - uses: bufbuild/buf-action@v1
+        with:
+          version: 1.49.0
+          token: ${{ secrets.BUF_TEMPORALIO_TOKEN }}
@@ -0,0 +1,6 @@
+# These owners will be the default owners for everything in
+# the repo. Unless a later match takes precedence,
+# @temporalio/saas will be requested for review when
+# someone opens a pull request.
+
+*       @temporalio/saas
@@ -1,17 +1,21 @@
-# Temporal cloud api proto files (Preview)
+# Temporal Cloud Operations API (Public Preview)
 
-> These apis are currently preview only and access is restricted. They are not meant for production use and could change. Please reach out to Temporal support to request preview access.
+> aka the Cloud Ops API  
+> These apis (proto files) are currently offered as a Public Preview. While they are production worthy, they are subject to change. Please reach out to Temporal Support if you have questions.
 
 ## How to use
 
-Copy over the protobuf files under [temporal](temporal) directory to the project directory and then use [grpc](https://grpc.io/docs/) to compile and generate code in the desired programming language.
+To use the Cloud Ops API in your project, preform the following 4 steps:
+1. Copy over the protobuf files under [temporal](temporal) directory to your desired project directory
+2. Use [gRPC](https://grpc.io/docs/) to compile and generate code in your desired programming language, typically handled as a part of your code build process
+3. Create a client connection in your code using a Temporal Cloud API Key (see [Samples](#samples) below)
+4. Use the Cloud Operations API services to automate Cloud Operations, such as creating users or namespaces
 
 ### API Version
 
 The client is expected to pass in a `temporal-cloud-api-version` header with the api version identifier with every request it makes to the apis. The backend will use the version to safely mutate resources. The `temporal:versioning:min_version` label specifies the minimum version of the API that supports the field.
 
-Current Version:
-https://github.com/temporalio/api-cloud/blob/main/VERSION#L1C1-L1C14
+Current Version `v0.4.0`
 
 ### URL
 
@@ -22,4 +26,11 @@ saas-api.tmprl.cloud:443
 
 ## Samples
 
-Refer [cloud-samples-go](https://github.com/temporalio/cloud-samples-go) repository for demonstration on how a project can copy and build Go clients.
+Refer to the [cloud-samples-go](https://github.com/temporalio/cloud-samples-go/blob/main/cmd/worker/README.md) sample repository for how to use the cloud ops api in Go.
+> This sample demonstrates how to automate Temporal Cloud operations using Temporal Workflows that make Cloud Ops API requests within Workflow Activities ([Worker Sample README](https://github.com/temporalio/cloud-samples-go/tree/main/cmd/worker)).  
+> See [here](https://github.com/temporalio/cloud-samples-go/blob/60d5cbca8696c87fb184efc56f5ae117561213d2/client/api/client.go#L16) for a quick reference showing you how to connect to Temporal Cloud with an API Key for the Cloud Ops API in Go.
+
+Refer to the [temporal-cloud-api-client-typescript](https://github.com/steveandroulakis/temporal-cloud-api-client-typescript) sample repository for how to use the cloud ops api in Typescript.  
+Refer to the [temporal-cloud-api-client-java](https://github.com/steveandroulakis/temporal-cloud-api-client-java) sample repository for how to use the cloud ops api in Java.  
+Refer to the [temporal-cloud-api-client-kotlin](https://github.com/steveandroulakis/temporal-cloud-api-client-kotlin) sample repository for how to use the cloud ops api in Kotlin.
+> The Java, Typescript, and Kotlin sample apps all provide a simple HTML UI that demonstrates how to use the Cloud Ops API to CRUD Namespaces and Users.
@@ -1 +1 @@
-2024-10-01-00
+v0.5.1
@@ -4,5 +4,10 @@ deps:
   - remote: buf.build
     owner: googleapis
     repository: googleapis
-    commit: 711e289f6a384c4caeebaff7c6931ade
-    digest: shake256:e08fb55dad7469f69df00304eed31427d2d1576e9aab31e6bf86642688e04caaf0372f15fe6974cf79432779a635b3ea401ca69c943976dc42749524e4c25d94
+    commit: e93e34f48be043dab55be31b4b47f458
+    digest: shake256:93dbe51c27606999eef918360df509485a4d272e79aaed6d0016940379a9b06d316fc5228b7b50cca94bb310f34c5fc5955ce7474f655f0d0a224c4121dda3c1
+  - remote: buf.build
+    owner: temporalio
+    repository: api
+    commit: 95c35fbcc7f647cbb0facec6fb60aca8
+    digest: shake256:f40de31043fe8dbf433395ebd2c7fef6a395582a856da1476cf5bb8ec32c7091a2c21208590effa59715bcceceec8ab2a6331919eb260d72b1091d9c76fd535b
@@ -1,6 +1,8 @@
 version: v1
+name: buf.build/temporalio/cloud-api
 deps:
   - buf.build/googleapis/googleapis
+  - buf.build/temporalio/api:v1.43.0
 breaking:
   use:
     - FILE

@@ -256,6 +256,25 @@ message AddNamespaceRegionResponse {
     temporal.api.cloud.operation.v1.AsyncOperation async_operation = 1;
 }
 
+message DeleteNamespaceRegionRequest {
+    // The namespace to delete a region.
+    string namespace = 1;
+    // The id of the standby region to be deleted.
+    // The GetRegions API can be used to get the list of valid region ids.
+    // Example: "aws-us-west-2".
+    string region = 2;
+    // The version of the namespace for which this delete region operation is intended for.
+    // The latest version can be found in the GetNamespace operation response.
+    string resource_version = 3;
+    // The id to use for this async operation - optional.
+    string async_operation_id = 4;
+}
+
+message DeleteNamespaceRegionResponse {
+    // The async operation.
+    temporal.api.cloud.operation.v1.AsyncOperation async_operation = 1;
+}
+
 message GetRegionsRequest {
 }
 
@@ -463,11 +482,18 @@ message GetUserGroupsRequest {
     string display_name = 4;
     // Filter groups by the google group specification - optional.
     GoogleGroupFilter google_group = 5;
+    // Filter groups by the SCIM group specification - optional.
+    SCIMGroupFilter scim_group = 6;
+
 
     message GoogleGroupFilter {
         // Filter groups by the google group email - optional.
         string email_address = 1;
     }
+    message SCIMGroupFilter {
+        // Filter groups by the SCIM IDP id - optional.
+        string idp_id = 1;
+    }
 }
 
 message GetUserGroupsResponse {
@@ -556,6 +582,58 @@ message SetUserGroupNamespaceAccessResponse {
     temporal.api.cloud.operation.v1.AsyncOperation async_operation = 1;
 }
 
+message AddUserGroupMemberRequest {
+    // The id of the group to add the member for.
+    string group_id = 1;
+
+    // The member id to add to the group.
+    temporal.api.cloud.identity.v1.UserGroupMemberId member_id = 2;
+
+    // The id to use for this async operation.
+    // Optional, if not provided a random id will be generated.
+    string async_operation_id = 3;
+}
+
+message AddUserGroupMemberResponse {
+    // The async operation.
+    temporal.api.cloud.operation.v1.AsyncOperation async_operation = 1;
+}
+
+message RemoveUserGroupMemberRequest {
+    // The id of the group to add the member for.
+    string group_id = 1;
+
+    // The member id to add to the group.
+    temporal.api.cloud.identity.v1.UserGroupMemberId member_id = 2;
+
+    // The id to use for this async operation.
+    // Optional, if not provided a random id will be generated.
+    string async_operation_id = 3;
+}
+
+message RemoveUserGroupMemberResponse {
+    // The async operation.
+    temporal.api.cloud.operation.v1.AsyncOperation async_operation = 1;
+}
+
+message GetUserGroupMembersRequest {
+    // The requested size of the page to retrieve - optional.
+    // Cannot exceed 1000. Defaults to 100.
+    int32 page_size = 1;
+    // The page token if this is continuing from another response - optional.
+    string page_token = 2;
+
+    // The group id to list members of.
+    string group_id = 3;
+}
+
+message GetUserGroupMembersResponse {
+    // The list of group members
+    repeated temporal.api.cloud.identity.v1.UserGroupMember members = 1;
+    // The next page's token.
+    string next_page_token = 2;
+}
+
 message CreateServiceAccountRequest {
     // The spec of the service account to create.
     temporal.api.cloud.identity.v1.ServiceAccountSpec spec = 1;

@@ -128,6 +128,13 @@ service CloudService {
         };
     }
 
+    // Delete a region from a namespace
+    rpc DeleteNamespaceRegion (DeleteNamespaceRegionRequest) returns (DeleteNamespaceRegionResponse) {
+        option (google.api.http) = {
+            delete: "/cloud/namespaces/{namespace}/regions/{region}",
+        };
+    }
+
     // Get all regions
     rpc GetRegions (GetRegionsRequest) returns (GetRegionsResponse) {
         option (google.api.http) = {
@@ -261,6 +268,28 @@ service CloudService {
         };
     }
 
+    // Add a member to the group, can only be used with Cloud group types.
+    rpc AddUserGroupMember(AddUserGroupMemberRequest) returns (AddUserGroupMemberResponse) {
+        option (google.api.http) = {
+            post: "/cloud/user-groups/{group_id}/members",
+            body: "*"
+        };
+    }
+
+    // Remove a member from the group, can only be used with Cloud group types.
+    rpc RemoveUserGroupMember(RemoveUserGroupMemberRequest) returns (RemoveUserGroupMemberResponse) {
+        option (google.api.http) = {
+            post: "/cloud/user-groups/{group_id}/remove-member",
+            body: "*"
+        };
+    }
+
+    rpc GetUserGroupMembers(GetUserGroupMembersRequest) returns (GetUserGroupMembersResponse) {
+        option (google.api.http) = {
+            get: "/cloud/user-groups/{group_id}/members",
+        };
+    }
+
     // Create a service account.
     rpc CreateServiceAccount(CreateServiceAccountRequest) returns (CreateServiceAccountResponse) {
         option (google.api.http) = {