# Cloud Ops API

> The Temporal Cloud Operations API (Cloud Ops) allows programmatic management of Temporal Cloud Control Plane resources.

> **Public Preview**

The Temporal Cloud Operations API, or the Cloud Ops API, is an open source, public [HTTP API](https://saas-api.tmprl.cloud/docs/httpapi.html#description/introduction) and [gRPC API](https://github.com/temporalio/cloud-api/tree/main) for programmatically managing Temporal Cloud Control Plane resources, including [Namespaces](/cloud/namespaces), [Users](/cloud/manage-access/users), [Service Accounts](/cloud/manage-access/service-accounts), [API keys](/cloud/api-keys), and others. The Temporal Cloud [Terraform Provider](/cloud/terraform-provider), [tcld CLI](/cloud/tcld), and Web UI all use the Cloud Ops API.

## Develop applications with the Cloud Ops API

You can use the HTTP API or the gRPC API depending on how you need to integrate with your platform.

- HTTP: `https://saas-api.tmprl.cloud`
- gRPC: `saas-api.tmprl.cloud:443`

If you connect to Temporal Cloud over [AWS PrivateLink](/cloud/connectivity/aws-connectivity) or [GCP Private Service Connect](/cloud/connectivity/gcp-connectivity), configure private DNS for `saas-api.tmprl.cloud` so control-plane clients (Cloud Ops API, Terraform, tcld) reach the private endpoint.

### Prerequisites

These prerequisites are required for using either HTTP or gRPC.

- A Temporal Cloud [User](/cloud/manage-access/users) or [Service Account](/cloud/manage-access/service-accounts)
- An [API Key](/cloud/api-keys#manage-api-keys) for authentication (owned by that User or Service Account)

Required [roles and permissions](/cloud/manage-access/roles-and-permissions) vary by operation. Some account-wide management operations require Account Owner or Global Admin. Others work with Developer, Finance Admin, Namespace Admin, or custom roles.

### Use cases

Some common reasons you might use the API are to:

- Provision Namespaces per environment or tenant via pipelines.
- Bootstrap new projects by creating users, assigning roles, and creating Namespaces via custom scripts.
- Rotate service account keys on a schedule with a job.
- Audit and report access across orgs with scheduled HTTP requests.

### Using HTTP

[The HTTP API](https://saas-api.tmprl.cloud/docs/httpapi.html#description/introduction) supports the same operations as the [gRPC API](#using-grpc), but it's usable via standard HTTP methods and authentication. This may be a more convenient option if you are writing automation scripts for CI/CD or you can't use gRPC due to network policies, proxies, tooling gaps, or language/runtime constraints. Since it's standard HTTP, it's language agnostic giving you the ability to run cloud operations consistently.

> **📝 Note:**
> This *does not* allow interaction with individual Workflows or Activities via HTTP.

### Using gRPC

*For Go developers:*
- Use the [Go SDK](https://github.com/temporalio/cloud-sdk-go) for the simplest setup experience

*For other programming languages:*
- Basic familiarity with gRPC and Protocol Buffers (protobuf)
- [Protocol Buffers](https://github.com/protocolbuffers/protobuf/releases)
- [gRPC](https://grpc.io/docs/languages/) in your preferred programming language

You can use the provided proto files to generate client libraries in your desired programming language, and then use that client to access the gRPC API. You can also find the [full gRPC docs on Buf](https://buf.build/temporalio/cloud-api/docs/main:temporal.api.cloud.cloudservice.v1#temporal.api.cloud.cloudservice.v1.CloudService).

#### Using the Go SDK

If you're developing in Go, we recommend using the [Go SDK](https://github.com/temporalio/cloud-sdk-go) 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. You can also use the [Go samples](https://github.com/temporalio/cloud-samples-go) to help you get started with the Cloud Ops API using the Go SDK.

To start using the Go SDK with the Cloud Ops API, follow these steps:

1. Install the Go SDK:
   ```go
   go get go.temporal.io/cloud-sdk@latest
   ```

2. Import and use the SDK:
   ```go
   import (
       "go.temporal.io/cloud-sdk/cloudclient"
   )
   ```

3. The Go SDK provides pre-built client interfaces that handle authentication and connection setup. Refer to the [Go samples](https://github.com/temporalio/cloud-samples-go) for detailed usage examples, including [Cloud Ops API client setup](https://github.com/temporalio/cloud-samples-go/blob/main/client/api/client.go).

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](https://github.com/temporalio/cloud-api/tree/main/temporal/api/cloud) and compile them manually.

Use [gRPC](https://grpc.io/docs/) to compile and generate code in your preferred [programming language](https://grpc.io/docs/#official-support). The steps below use Python as an example and require [Python's gRPC tools](https://grpc.io/docs/languages/python/quickstart/#grpc-tools) to be installed, but the approach can be adapted for other supported programming languages.

You can also generate clients from the published Buf module at [buf.build/temporalio/cloud-api](https://buf.build/temporalio/cloud-api).

1. Clone the Temporal Cloud API repository:

   ```command
   git clone https://github.com/temporalio/cloud-api.git
   cd cloud-api
   ```

2. Compile the Protobuf files from the repository root (protos live under `temporal/` and import each other):

   ```command
   python -m grpc_tools.protoc \
     -I. \
     --python_out=. \
     --grpc_python_out=. \
     $(find temporal -name '*.proto')
   ```

   - `-I.` adds the repository root to the import path.
   - `--python_out=` and `--grpc_python_out=` set the output directories for generated classes.
   - `find temporal -name '*.proto'` includes all Cloud Ops API protos and their dependencies under `temporal/`.

   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.

3. Import the generated files into your application and call the Cloud Ops API. Handle authentication with an API key and set the API version header as described in [Usage guidelines](#usage-guidelines).

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

Use the `temporal-cloud-api-version` header to select an API version. The backend uses this version to safely mutate resources. The current API version is in the [`cloud-api` VERSION file](https://github.com/temporalio/cloud-api/blob/main/VERSION).

**gRPC**

gRPC clients must send a `temporal-cloud-api-version` header on every request.

**HTTP**

For HTTP clients, the version header is optional. If omitted, the HTTP gateway defaults it to the latest API version. This supports simple `curl` usage without looking up a version first.

For production HTTP automation, still pin an explicit version so behavior does not change when the gateway’s latest version advances.

### Connection URL

- gRPC: `saas-api.tmprl.cloud:443`
- HTTP: `https://saas-api.tmprl.cloud`

### Engagement steps

1. Generate an [API Key for authentication](/cloud/api-keys#manage-api-keys). Required permissions vary by operation; see [roles and permissions](/cloud/manage-access/roles-and-permissions).
2. Establish a secure connection. For Go, see [Cloud Ops API client setup](https://github.com/temporalio/cloud-samples-go/blob/main/client/api/client.go).
3. Execute operations. For request and response messages, see `cloudservice/v1/request_response.proto`. For services, see `cloudservice/v1/service.proto`.

## 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: 160 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 the limit regardless of the number of users or service accounts making requests.

### Per-identity rate limits

**User rate limit: 40 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: 80 RPS per service account**

This limit applies to all requests made by each service account through any client (tcld, Cloud Ops API).

**Asynchronous operations: 10 concurrent operations at a time**

By default, each account can have up to 10 long-running (asynchronous) mutating operations in flight at once. This limit applies to a subset of create, update, and delete operations (for example Namespace, User, API Key, Export Sink, and Service Account mutations), not every RPC that returns an async operation.

### 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](/cloud/support#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!

You can provide feedback through the following channels:

- Submit request or feedback through a [support ticket](/cloud/support#support-ticket)
- Open an issue in the [GitHub Repo](https://github.com/temporalio/cloud-api)