Skip to main content

API Keys - Temporal Cloud feature guide

Support, stability, and dependency info

Temporal Cloud supports secure programmatic access through API Key Authentication.

Overview​

Temporal Cloud API Keys facilitate user-level authentication. Each key is unique to a single user and ties directly to their Role-Based Access Control (RBAC) settings, ensuring secure and appropriate access.

The process is as follows:

API Key (authentication) → User (identity) → RBAC (authorization)

These API Keys are integral for authenticating Temporal Cloud operator tools, including Temporal Cloud CLI (tcld) and the Temporal Cloud Operations API.

Users have the autonomy to create, delete, and update access to their API Keys through the Cloud UI or tcld.

API Keys are an opt-in feature that must be enabled by a Global Administrator for use. For broader oversight, Global Administrators can manage user's API Keys using the same interfaces. For instructions on API Key Management for your organization, see global Administrator API Key Management.

Get started​

To get started, ensure you're a Temporal Cloud user. If you don't have an account with Temporal, sign up here.

Prerequisites​

Use API Keys​

API Keys can be used in the tcld or in the Cloud Ops API.

How can I use the API Key with tcld?

To use your API Key with tcld, use one of the following methods:

  • --api-key flag
  • TEMPORAL_CLOUD_API_KEY environment variable

How can I use the API Key with Cloud Ops API?

To use your API Key with the Cloud Ops API, securely pass your API Key in your Cloud Ops API client.

For a complete example, see Cloud Samples in Go.

Manage API Keys​

Manage your personal API Keys by creating, deleting, or updating access to them using the Cloud UI or tcld.

Global Administrator API Key Management​

note

API Keys are not enabled for by default. You must enable API Key access to allow the creation of API Keys.

Global Administrators can monitor, manage, update access, and delete API Keys for any user within their account.

To manage your accounts API Keys

  1. Login to the Cloud UI.
  2. Select Settings and choose API Keys.

From here, you can update access to the API Key for an account using the Enable and Disable toggle. You can also disable or delete an individual User API Key using the vertical ellipsis at the right of the API Keys row.

Generate an API Key​

note

Once generated, copy and securely save the API Key. It will be displayed only once for security purposes.

Generate an API Key using one of the following methods.

Using the Cloud UI​

To generate an API Key using the Cloud UI:

  1. Login to the Cloud UI.
  2. Navigate to Profile Page → API Keys.
  3. Select Create API Key and provide the following:
    1. Name
    2. Description
    3. Expiration Date
  4. Select Generate API Key.
note

Temporal supports up to a 90-day duration for API Keys.

Using the tcld​

To generate an API Key using tcld, use the tcld apikey create command.

  1. Authenticate your Temporal Cloud account using the login command.
  2. Create an API Key using the apikey create command.

For example:

tcld login
tcld apikey create --name Your-Key-Name --description YourDescription --duration 24h
note

Use tcld to create API Keys with a day level expiration by day.

Delete an API Key​

Delete an API Key using one of the following methods.

Using the Cloud UI​

To delete an API Key using the Cloud UI

  1. Login to the Cloud UI.
  2. Navigate to your Profile Page → API Keys.
  3. Select the three vertical dots to the right of the API Key's row and choose Delete.
  4. Choose Delete.

Using the tcld​

To delete an API Key using tcld, pass the API Key ID to the tcld apikey delete command.

  1. Authenticate your Temporal Cloud account using the login command.
  2. Delete the API Key using the apikey delete command.
tcld apikey delete --id <your-api-key-id>

Update access to an API Key​

You can update access to an API Key by enabling or disabling it.

After disabling an API Key, that API Key will no longer be able to authenticate with Temporal Cloud. Only enabled keys can authenticate with Temporal Cloud.

Using the Cloud UI​

To update access to an API Key using the Cloud UI, follow these steps:

  1. Login to the Cloud UI.
  2. Navigate to Profile Page → API Keys.
  3. Select the three vertical dots to the right of the API Key's row and choose Disable.

Using the tcld​

To update access to an API Key using the tcld, follow these steps:

  1. Login to tcld using either SSO or an API Key.
  2. Use the apikey disable/enable commands to disable/enable the key.
tcld apikey disable --id <api-key-id>
tcld apikey enable --id <api-key-id>

Best practices​

  • Keep it secret | Keep it safe: Treat your API Key as you would a password. Don't expose it in client-side code, public repositories, or other easily accessible places.
  • Rotate regularly: Change your API Keys periodically to minimize potential harm from any leaks.
  • Monitor usage: Keep an eye on the usage metrics and logs. If you notice unexpected or unauthorized activity, revoke the key immediately.
  • KMS: Use a KMS to reduce risks of key leak.

Troubleshooting​

Invalid API Key Errors: Ensure you copied the key correctly and that it hasn't been revoked (deleted) or expired.

Frequently asked questions​

Q: Can I have multiple API Keys?

A: Yes, you can generate multiple keys to use in different services or for team members.

Q: How many API Keys can I have?

A: 10 per User.

Q: Is there an expiration for the API Keys?

A: Yes. During Preview, API Keys have an upper bound of 90 days. In a subsequent release, long-lived API Keys will become available. Temporal recommends rotating API Keys periodically.

Q: What should I do if I lost my API Key secret?

A: For security reasons, we only display the full key once upon creation. If you lose it, you'll need to generate a new one.

Provide feedback​

Your input is valuable. While API Keys are in a Public Preview release status for Temporal Cloud, we welcome your feedback.

You can provide feedback through the following channels:

  • Submit request or feedback through a ZenDesk ticket