# Manage API keys Temporal Cloud API keys offer industry-standard identity-based authentication for Temporal users and [Service Accounts](/cloud/service-accounts). This document introduces Temporal Cloud's API key features: - [API key overview](#overview) - [API key best practices](#best-practices) - [Global Administrator and Account Owner API key management](#manage-api-keys) - [User API key management](#user-api-keys) - [Manage API keys for Service Accounts](#serviceaccount-api-keys) - [API keys for Namespace authentication](#namespace-authentication) - [Use API keys to authenticate](#using-apikeys) - [Troubleshoot your API key use](#troubleshooting) - [API keys: Frequently Asked Questions](#faqs) ## API key overview Each Temporal Cloud API key is a unique identity linked to role-based access control (RBAC) settings to ensure secure and appropriate access. The authentication process follows this pathway: ![API key (authentication) → Identity (user or Service Account) → RBAC (authorization)](/img/cloud/apikeys/apikeyrbac.png) ## API key best practices - **Keep it secret; keep it safe**: Treat your API key like a password. Do not expose it in client-side code, public repositories, or other easily accessible locations. - **Rotate keys regularly**: Change your API keys periodically to reduce risks from potential leaks. - **Design your code for key updates**: Use key management practices that retrieve your API keys without hard-coding them into your apps. This lets you restart your Workers to refresh your rotated keys without recompiling your code. - **Monitor API key usage**: Check usage metrics and logs regularly. Revoke the key immediately if you detect any unexpected or unauthorized activity. - **Use a Key Management System (KMS)**: Employ a Key Management System to minimize the risk of key leaks. For guidance on which identities should own API keys, when to use Namespace-scoped Service Accounts, and how to align API keys with your Namespace topology, see [Managing Temporal Cloud access control](/best-practices/cloud-access-control). ### API key use cases API keys are used for the following scenarios: - _**Cloud operations automation**_: API keys work with Temporal Cloud operational tools, including [`tcld`](/cloud/tcld), [Cloud Ops APIs](/ops), and [the Terraform provider](/cloud/terraform-provider). Use them to manage your Temporal Cloud account, Namespaces, certificates, and user identities. - _**Namespace authentication**_: API keys serve as an authentication mechanism for executing and managing Workflows via the SDK and Temporal CLI, offering an alternative to mTLS-based authentication. ### API key supported tooling Use API keys to authenticate with: - [The Temporal CLI](/cli) - [Temporal SDKs](/develop) - [`tcld`](/cloud/tcld/index.mdx) - [The Cloud Operations API](/cloud/operation-api.mdx) - [Temporalʼs Terraform provider](/cloud/terraform-provider) ### API key permissions API keys support both users and Service Accounts. Here are the differences in their permissions: - Any user can create, delete, and update their _own_ API key using the Cloud UI or `tcld`. - Only Global Administrators and Account Owners can create, delete, and update access to API keys for all types of Service Accounts. - Namespace Admins can create, delete, and update access to API keys for the Namespace-scoped Service Accounts they administer. ### API key prerequisites Check these setup details before using API keys: - The Global Administrator or Account Owner may need to [enable API keys access](#manage-api-keys) for your Temporal Account. - Have access to the [Temporal Cloud UI](https://cloud.temporal.io/) or Temporal Cloud CLI ([tcld](https://docs.temporal.io/cloud/tcld/)) to create an API key. ## Global Administrator and Account Owner API key management Global Administrators and Account Owners can monitor, manage, disable, and delete API keys for any user or Service Account within their account. To manage your account’s API keys: 1. [Log in](https://cloud.temporal.io/) to the Temporal Cloud UI. 1. Go to [Settings → API Keys](https://cloud.temporal.io/settings/api-keys) Administrators can disable the creation of new API keys using the **Disable Create API Keys** button on the **API Keys** Settings page. Existing API keys can still be used to authenticate into Temporal Cloud normally until they are either disabled, deleted, or expired. To disable or delete an individual API key use the vertical ellipsis menu in the API key table row. To find an API key, you can filter by API key state and identity type (Global Administrators and Account Owners only). > **⚠️ Caution:** > DISABLED API KEYS > > Deleting or disabling a key removes its ability to authenticate into Temporal Cloud. If you delete or disable an API key > being used by Workers to run a Workflow, those Workers will be unable to connect to Temporal until a new API key secret > is created and configured. > ## User API key management Manage your personal API keys with the Temporal Cloud UI or `tcld`. These sections show you how to generate, manage, and remove API keys for a user. ### Generate an API key Create API keys using one of the following methods: > **⚠️ Caution:** > > - Once generated, copy and securely save the API key. It will be displayed only once for security purposes. > #### Generate API keys with the Temporal Cloud UI [Log in](https://cloud.temporal.io/) to the Temporal Cloud UI and navigate to your [Profile Page → API Keys](https://cloud.temporal.io/profile/api-keys). Then select **Create API key** and provide the following information: - **API key name**: A short, identifiable name for the key - **API key description**: A longer description of the key's use - **Expiration date**: The end date for the API key Finish by selecting **Generate API Key**. #### Generate API keys with tcld To generate an API key, log into your account and issue the following command: ```command tcld login tcld apikey create \ --name \ --description "" \ --duration ``` Duration specifies the time until the API key expires, for example: "30d", "4d12h", etc. ### Enable or Disable an API key You can enable or disable API keys. When disabled, an API key cannot authenticate with Temporal Cloud. #### Manage API key state with the Temporal Cloud UI Follow these steps: 1. [Log in](https://cloud.temporal.io/) to the Temporal Cloud UI. 1. Go to your [Profile Page → API Keys](https://cloud.temporal.io/profile/api-keys). 1. Select the vertical ellipsis menu in the API key table row. 1. Choose **Enable** or **Disable**. #### Manage API Key State with tcld To manage an API key, log into your account and use one of the following commands to enable or disable it: ```command tcld login tcld apikey disable --id tcld apikey enable --id ``` ### Delete an API key Deleting an API key stops it from authenticating with Temporal Cloud. > **⚠️ Caution:** > > Deleting an API key used by Workers to run a Workflow will cause it to fail unless you rotate the key with a new one. > This can affect long-running Workflows that outlast the API key's lifetime. > #### Delete API keys with the Temporal Cloud UI Follow these steps to remove API keys: 1. [Log in](https://cloud.temporal.io/) to the Temporal Cloud UI. 1. Navigate to your [Profile Page → API Keys](https://cloud.temporal.io/profile/api-keys). 1. Select the vertical ellipsis menu in the API key table row. 1. Choose **Delete**. #### Delete API keys with tcld To delete an API key, log into your account and issue the following: ```command tcld login tcld apikey delete --id ``` ### Rotate an API key Temporal API keys automatically expire based on the specified expiration time. Follow these steps to rotate API keys: 1. Create a new key. You may reuse key names if that helps. 1. Ensure that both the original key and new key function properly before moving to the next step. 1. Switch clients to load the new key and start using it. 1. Delete the old key after it is no longer in use. For a broader machine-identity rotation strategy across API keys and Service Accounts, see [Managing Temporal Cloud access control](/best-practices/cloud-access-control). ## Manage API keys for Service Accounts Global Administrators and Account Owners can manage and generate API keys for _all_ Service Accounts in their account. Namespace Admins can manage and generate API keys for the Namespace-scoped Service Accounts they administer. This is different for non-admin users, who manage and generate their own API keys. ### Generate an API Key for a Service Account Create API keys for Service Accounts using one of the following methods: > **⚠️ Caution:** > > - Once generated, copy and securely save the API key. It will be displayed only once for security purposes. > #### Generate API Keys with the Temporal Cloud UI [Log in](https://cloud.temporal.io/) to the Temporal Cloud UI. Global Administrators or Account Owners can go to [Settings → API Keys](https://cloud.temporal.io/settings/api-keys). Namespace Admins can go to [Profile Page → API Keys](https://cloud.temporal.io/profile/api-keys). Select **Create API Key**, then choose **Service Account** from the "Create an API key for" dropdown. In the "Mapped to identity" input box, select a Service Account and provide the following information: - **API key name**: A short, identifiable name for the key - **API key description**: A longer description of the key's use - **Expiration date**: The end date for the API key Finish by selecting **Generate API Key**. #### Generate API keys with tcld To create an API key for a Service Account, use `tcld apikey create` with the `--service-account-id` flag: ``` tcld apikey create \ --name \ --description "" \ --duration \ --service-account-id ``` ### Enable or Disable an API key Global Administrators and Account Owners can manage API key access for any user in their account using the Temporal Cloud UI or `tcld`. #### Manage keys with Temporal Cloud UI Follow these steps: 1. [Log in](https://cloud.temporal.io/) to the Temporal Cloud UI. 1. Global Administrators or Account Owners can go to [Settings → API Keys](https://cloud.temporal.io/settings/api-keys). Namespace Admins can go to [Profile Page → API Keys](https://cloud.temporal.io/profile/api-keys). 1. Find the API key. Use the vertical ellipsis menu in the table row and select the Disable/Enable option to perform the action. There may be a delay after changing the status. Once successful, the updated API key status will be shown in the row. #### Manage keys with tcld Use the `tcld apikey disable` or `tcld apikey enable` command to disable or enable an API key: ``` tcld login tcld apikey disable --id tcld apikey enable --id ``` This command is the same for users and Service Accounts. ### Delete an API key for a Service Account Global Administrators and Account Owners can delete API keys for any user or Service Account in their account using the Temporal Cloud UI or `tcld`. Deleting a key removes its ability to authenticate with Temporal Cloud. If you delete an API key used by a Worker to run a Workflow, that Worker will fail to connect to Temporal server unless you rotate the API key with a new one. #### Delete a Service Account API key with Temporal Cloud UI Follow these steps: 1. Go to [Settings → API Keys](https://cloud.temporal.io/settings/api-keys). 1. Locate the API key. Use the vertical ellipsis menu in the table row and select the Delete option. There may be a delay after deleting the API key. 1. Once successful, the updated API key status will be reflected in the row. #### Delete a Service Account API key with tcld Use the `tcld apikey delete` command to delete an API key. The process for deleting an API key is the same for a user or Service Account. ``` tcld login tcld apikey delete --id ``` ### Rotate a Service Account API key Temporal API keys automatically expire based on the specified expiration time. Follow these steps to rotate API keys: 1. Create a new key. You may reuse key names if that helps. 1. Ensure that both the original key and new key function properly before moving to the next step. 1. Switch clients to load the new key and start using it. 1. Delete the old key after it is no longer in use. > **💡 Tip:** > > Service Accounts can rotate their own API keys irrespective of their configured permissions. To use this feature, have > your Service Account create a new API key using the [Cloud Ops APIs](/ops) or [`tcld`](/cloud/tcld) before the current > one expires. Service Accounts cannot delete their own API keys without the requisite permissions, which helps keep > Workflow access secure. > ## API keys for Namespace authentication Create a Namespace with API key authentication as an alternative to mTLS-based authentication by selecting "Allow API key authentication" during setup. Use the gRPC Namespace endpoint: `..tmprl.cloud:7233`. This is the recommended endpoint for all Namespaces. For Namespaces with [High Availability](/cloud/high-availability), the Namespace endpoint automatically directs traffic to the active region, so Workers and Clients don't need to change endpoints during a failover. See [accessing Namespaces](/cloud/namespaces#access-namespaces) for more information on endpoint options. ## Use API keys to authenticate Authenticate with Temporal Cloud using API keys with the following clients: - [Temporal CLI](/cli) - [SDKs](/develop) - [Temporal Cloud CLI `tcld`](/cloud/tcld/index.mdx) - [The Cloud Operations API](/cloud/operation-api.mdx) - [Temporal’s Terraform Provider](/cloud/terraform-provider) ### Temporal CLI To use your API key with the Temporal CLI, either pass it with the `--api-key` flag or set an environment variable in your shell (recommended). The CLI automatically picks up the `TEMPORAL_API_KEY` environment variable from your shell. In addition to the API key, the following client options are required: - `--address`: Provide `..tmprl.cloud:7233` using your Namespace's info. - This can be copied from the Namespace UI's "Connect" box. - You can set the address using an environment variable. - `--namespace`: Provide `.` using your Namespace's info. - This can be copied from the top of the Namespace UI. - This can be set using an environment variable. For example, to connect to Temporal Cloud from the CLI using an environment variable for the API key: ```bash export TEMPORAL_API_KEY= temporal workflow list \ --address ..tmprl.cloud:7233 \ --namespace . ``` > **💡 Tip:** > ENVIRONMENT VARIABLES > > Do not confuse environment variables, set with your shell, with temporal env options. > ### SDKs To use your API key with a Temporal SDK, see the instructions in each SDK section. [How to connect to Temporal Cloud using an API Key with the Go SDK](/develop/go/client/temporal-client#connect-to-temporal-cloud) [How to connect to Temporal Cloud using an API Key with the Java SDK](/develop/java/client/temporal-client#connect-to-temporal-cloud) [How to connect to Temporal Cloud using an API Key with the Python SDK](/develop/python/client/temporal-client#connect-to-temporal-cloud) [How to connect to Temporal Cloud using an API Key with the TypeScript SDK](/develop/typescript/client/temporal-client#connect-to-temporal-cloud) [How to connect to Temporal Cloud using an API Key with the .NET SDK](/develop/dotnet/client/temporal-client#connect-to-temporal-cloud) ### tcld To use an API key with `tcld`, choose one of these methods: - Use the `--api-key` flag. - Set the `TEMPORAL_API_KEY` environment variable in your shell. > **💡 Tip:** > ENVIRONMENT VARIABLES > > Do not confuse environment variables, set with your shell, with temporal env options. > ### Cloud Ops API To use an API key with the [Cloud Ops API](/ops), securely pass the API key in your API client. For a complete example, see [Cloud Samples in Go](https://github.com/temporalio/cloud-samples-go/blob/1dd4254b6ed1937e361005c0144410e72b8a5542/client/api/apikey.go). ### Terraform Provider To use an API key with the [Temporal Terraform Provider](/cloud/terraform-provider), pass the API key as a provider argument. ## Troubleshoot your API key use **Invalid API key errors**: Check that you copied the key correctly and that it hasn't been revoked or expired. ## API keys: Frequently Asked Questions **Q: Can I issue and use multiple API keys for the same account?** A: Yes, you can generate multiple API keys for different services or team members. **Q: How many API keys can be issued at once?** A: Up to 10 non-expired keys per user and 20 non-expired keys per Service Account. **Q: Do API keys expire?** A: Yes, API keys expire based on the specified expiration date. Temporal recommends rotating API keys periodically. **Q: What's the maximum allowed expiration for an API key?** A: The maximum expiration time for an API key is 2 years. **Q: What happens if I misplace or lose my API bearer token/secret key?** A: The full key is displayed only once upon creation for security reasons. If you lose it, generate a new one. **Q: What is the `Generate API Key` button on the Namespace page?** A: The `Generate API Key` button on a Namespace page generates an API key with `Admin` permissions for the given Namespace and the maximum expiration time, which is 2 years. For additional details, refer to [Namespace-scoped Service Accounts](/cloud/service-accounts#scoped).