본문으로 건너뛰기

Manage API keys

Temporal Cloud API keys offer industry-standard identity-based authentication for Temporal users and Service Accounts. This document introduces Temporal Cloud's API key features:

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)

API key (authentication) → Identity (user or Service Account) → RBAC (authorization)

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.

API key use cases​

API keys are used for the following scenarios:

  • Cloud operations automation: API keys work with most Temporal Cloud operational tools, including tcld, Cloud Ops APIs, and the 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:

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 access using the Cloud UI or tcld.
  • Only Global Administrators and Account Owners can create, delete, and update access to API keys for Service Accounts.

API key prerequisites​

Check these setup details before using API keys:

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 to the Temporal Cloud UI.
  2. Select Settings and choose API keys.

Administrators can disable the creation of new API keys using the Disable 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 next to the API key row or view the API key detail page.

To find an API key, you can filter by API key state and identity type (Global Administrators and Account Owners only).

DISABLED API KEYS

Deleting or disabling a key removes its ability to authenticate into Temporal Cloud. If you delete or disable an API key for a running Workflow, that Workflow will fail 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:

주의
  • 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 to the Temporal Cloud UI and navigate to your Profile Page → 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 form 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:

tcld login
tcld apikey create \
    --name <api-key-name> \
    --description "<api-key-description>" \
    --duration <api-key-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 to the Temporal Cloud UI.
  2. Go to your Profile Page → API Keys.
  3. Select the three vertical dots next to the API key’s row.
  4. 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:

tcld login
tcld apikey disable --id <api-key-id>
tcld apikey enable --id <api-key-id>

Delete an API key​

Deleting an API key stops it from authenticating with Temporal Cloud.

주의

Deleting an API key for a running 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 to the Temporal Cloud UI.
  2. Navigate to your Profile Page → API keys.
  3. Select the three vertical dots next to the API key's row.
  4. Choose Delete.

Delete API keys with tcld​

To delete an API key, log into your account and issue the following:

tcld login
tcld apikey delete --id <api-key-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.
  2. Ensure that both the original key and new key function properly before moving to the next step.
  3. Switch clients to load the new key and start using it.
  4. Delete the old key after it is no longer in use.

Manage API keys for Service Accounts​

Global Administrators and Account Owners can manage API keys for all Service Accounts in their account and generate API keys for Service Accounts. This is different for users, who 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:

주의
  • 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 to the Temporal Cloud UI and go to API keys settings. 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 <api-key-name> \
    --description "<api-key-description>" \
    --duration <api-key-duration> \
    --service-account-id <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 into Temporal Cloud.
  2. Go to https://cloud.temporal.io/settings/api-keys and find the identity that owns the API key.
  3. Click the Disable/Enable button 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 <api-key-id>
tcld apikey enable --id <api-key-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 for a running Workflow, that Workflow will fail unless you rotate the API key with a new one.

Delete a Service Account API key with Temporal Cloud UI​

Follow these steps:

  1. Navigate to https://cloud.temporal.io/settings/api-keys.
  2. Locate the identity that owns the API key and click on the row to view the API keys associated with that identity.
  3. Click the Delete button. There may be a delay after deleting the API key.
  4. 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 <api-key-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.
  2. Ensure that both the original key and new key function properly before moving to the next step.
  3. Switch clients to load the new key and start using it.
  4. Delete the old key after it is no longer in use.
팁

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 or 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. The gRPC endpoint format for the Namespace depends on the authentication method:

  • For API key connections, use the gRPC regional endpoint <region>.<cloud_provider>.api.temporal.io:7233.

Use this gRPC endpoint in the Temporal CLI or SDK to connect to Temporal Cloud with an API key.

정보

For Namespaces with High Availability features with API key authentication enabled, use the gRPC Namespace endpoint: <namespace>.<account>.tmprl.cloud:7233. This allows automated failover without needing to switch endpoints.

See the following documentation for accessing Namespaces for more information.

Use API keys to authenticate​

Authenticate with Temporal Cloud using API keys with the following clients:

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 the Namespace's gRPC endpoint from the Namespace UI's gRPC endpoint box.
    • For API key connections, use the format <region>.<cloud_provider>.api.temporal.io:7233.
    • You can set the address using an environment variable.
  • --namespace: Provide the namespace.accountId from the top of the Namespace page in the UI.
    • Use the format <namespace_id>.<account_id>.
    • This can be set using an environment variable.
  • --tls: Use for a secure connection with the appropriate options.
    • 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:

export TEMPORAL_API_KEY=<key-secret>
temporal workflow list \
    --address <endpoint> \
    --namespace <namespace_id>.<account_id> \
    --tls
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

How to connect to Temporal Cloud using an API Key with the Java SDK

How to connect to Temporal Cloud using an API Key with the Python SDK

How to connect to Temporal Cloud using an API Key with the TypeScript SDK

How to connect to Temporal Cloud using an API Key with the .NET SDK

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.
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, securely pass the API key in your API client. For a complete example, see Cloud Samples in Go.

Terraform Provider​

To use an API key with the Temporal 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: Whats 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.