Cloud Ops API
Temporal Cloud Operations API is in Public Preview for Temporal Cloud.
The Temporal Cloud Operations API (Cloud Ops API) is an open source, public gRPC API for managing the automation of Users, Namespaces, and Temporal Cloud Accounts.
In addition to being available on GitHub, the proto files are also hosted on Buf, which provides a clean web interface for browsing and visualizing the APIs, and offers more streamlined dependency management. You can use the provided proto files to generate client libraries in your desired programming language.
SDKs and samples
We provide a Go SDK that compiles the proto files into Go bindings, offering a more idiomatic interface for Go developers. This SDK eliminates the need to manually compile protobuf files when working with Go.
We also provide Go samples to help you get started with the Cloud Ops API using the Go SDK.
Develop applications with the Cloud Ops API
This section walks you through the steps to develop applications with the Cloud Ops API, either through the Go SDK or by compiling the protobuf files for other programming languages.
Prerequisites
- Temporal Cloud user account
- API Key for authentication
For Go developers:
- Use the Go SDK for the simplest setup experience
For other programming languages:
- Basic familiarity with gRPC and Protocol Buffers (protobuf)
- Protocol Buffers
- gRPC in your preferred programming language
Using the Go SDK (Recommended for Go)
If you're developing in Go, we recommend using the Go SDK which provides pre-compiled Go bindings and a more idiomatic interface. The Go SDK handles all the protobuf compilation and provides ready-to-use Go types and client interfaces.
To start using the Go SDK with the Cloud Ops API, follow these steps:
-
Install the Go SDK:
go get github.com/temporalio/cloud-sdk-go
-
Import and use the SDK:
import (
"github.com/temporalio/cloud-sdk-go/client"
) -
The Go SDK provides pre-built client interfaces that handle authentication and connection setup. Refer to the Go samples for detailed usage examples.
The Go SDK eliminates the need to work directly with generated protobuf files and provides a more idiomatic Go experience.
Compile the API and use the generated code (For other languages)
For programming languages other than Go, download the gRPC protobufs from the Cloud Ops API repository and compile them manually.
Use gRPC to compile and generate code in your preferred programming language. The steps below use Python as an example and require Python's gRPC tools to be installed, but the approach can be adapted for other supported programming languages.
-
Clone the Temporal Cloud API repository:
git clone https://github.com/temporalio/cloud-api.git
cd cloud-api -
Copy Protobuf files:
- Navigate to the
temporal
directory. - Copy the protobuf files to your project directory.
- Navigate to the
-
Compile the Protobuf files:
python -m grpc_tools.protoc -I./ --python_out=./ --grpc_python_out=./ *.proto
-I
specifies the directory of the.proto
files.--python_out=
sets the output directory for generated Python classes.--grpc_python_out=
sets the output directory for generated gRPC service classes.*.proto
processes all.proto
files.
After compiling the Protobuf files, you will have generated code files in your project directory. These files enable interaction with the Temporal Cloud API in your chosen programming language.
-
Import the Generated Files:
- Locate the Python files (.py) generated in your project directory.
- Import these files into your Python application where you intend to interact with the Temporal Cloud API.
-
Utilize the API:
- Use the classes and methods defined in the imported files to communicate with the Temporal Cloud services.
- Ensure to handle any required authentication or configuration as needed for Temporal Cloud.
This approach can be adapted for other programming languages by following their respective import and usage conventions for the generated code files.
Usage guidelines
When interacting with the Temporal Cloud Ops API, follow these guidelines:
- API version header:
- Always include the
temporal-cloud-api-version
header in your requests, specifying the API version identifier. - The current API version can be found here.
- Always include the
- Connection URL:
- Connect to the Temporal Cloud using the gRPC URL:
saas-api.tmprl.cloud:443
.
- Connect to the Temporal Cloud using the gRPC URL:
- Engagement steps:
- Generate API key:
- Obtain an API Key for authentication. Note that many operations may require Admin privileges.
- Set up client:
- Establish a secure connection to the Temporal Cloud. Refer to the example Client setup in Go for guidance.
- Execute operations:
- For operation specifics, refer to the
cloudservice/v1/request_response.proto
for gRPC messages andcloudservice/v1/service.proto
for gRPC services.
- For operation specifics, refer to the
- Generate API key:
Rate limits
The Temporal Cloud Operations API implements rate limiting to ensure system stability and fair usage across all users. Rate limits are applied based on identity type, with different limits for users and service accounts.
Account-level rate limit
Total rate limit: 40 requests per second (RPS)
This limit applies to all requests made to the Temporal Cloud control plane by any client (tcld, UI, Cloud Ops API) or identity type (user, service account) within your account. The total account throughput cannot exceed 160 RPS regardless of the number of users or service accounts making requests.
Per-identity rate limits
User rate limit: 10 RPS per user
This limit applies to all requests made by each user through any client (tcld, UI, Cloud Ops API), regardless of the authentication method used (SSO or API keys).
Service account rate limit: 20 RPS per service account
This limit applies to all requests made by each service account through any client (tcld, Cloud Ops API).
Important considerations
- Rate limits are enforced across all Temporal Cloud control plane operations
- Multiple clients used by the same identity (user or service account) share the same rate limit
- Authentication method (SSO, API keys) does not affect rate limiting
- These limits help ensure system stability and prevent any single account or identity from overwhelming the service
Request limit increases
If your use case requires higher rate limits, you can request an increase by submitting a support ticket. When requesting a limit increase, please provide:
- Your current usage patterns and requirements
- The specific limits you need increased
- A description of your use case and why higher limits are necessary
Provide feedback
Your input is valuable. While the Temporal Cloud Ops API is in a Public Preview release status, we welcome your feedback.
You can provide feedback through the following channels:
- Submit request or feedback through a ZenDesk ticket
- Open an issue in the GitHub Repo