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>

API Keys for Client Connections​

Temporal Cloud supports secure programmatic access through API Key Authentication.

Overview​

Temporal Cloud API Keys facilitate identity-level authentication, for Users and Service Accounts. Each key is unique to a single identity and ties directly to the identity's Role-Based Access Control (RBAC) permissions, ensuring secure and appropriate access.

The relationship is as follows:

API Key (authentication) → User or Service Account (identity) → RBAC (authorization)

These API Keys are used to authenticate Temporal Cloud operator tools, including Temporal Cloud CLI (tcld) and the Temporal Cloud Operations API (Cloud Ops API), and Client Connection tools, including the Temporal CLI and SDKs.

The API Key is the authentication token that can be used in the Temporal CLI, SDKs, tcld, the Cloud Operations API, and the Terraform Provider. The gRPC endpoint used in the Temporal CLI and/or SDKs to connect to Temporal Cloud.

  • For an mTLS connection, the endpoint is in the format <namespace>.<account>.tmprl.cloud:7233.
  • For an API Key connection, the endpoint is in the format <region>.<cloud_provider>.api.temporal.io:7233 The gRPC header is the connection information supplied by the user in the Temporal CLI or SDK when connecting to Temporal Cloud using an API Key. Currently, in most SDKs and the CLI, the gPRC header should include a Bearer Token with the API Key and a Namespace header, specifically temporal-namespace.

Temporal Cloud API Keys functionality is designed for 3 types of use:

  1. User created API Keys - if enabled, users can create, delete, and update their own API Keys through the Cloud UI or tcld.
  2. Service Account created API Keys - Global Administrators can create, delete, and update API Keys for a Service Account.
  3. API Key governance - Temporal Cloud provides affordances for Global Administrators to govern and control API Key use within their accounts. Global Administrators can enable/disable API Keys for their accounts, and disable/delete API Keys for any User and/or Service Account.

API Keys can be used in:

By default, API Keys must be enabled by a Global Administrator before use. This action is an account-level setting.

Get started​

Prerequisites

Temporal CLI​

To use your API Key with the Temporal CLI, you can pass in the API Key to each command using the --api-key flag or an environment variable (recommended).

In addition to passing in the API Key, the following client options are required:

  • --address: Provide the Namespace's gRPC endpoint located in the Namespace UI in the gRPC endpoint box.
    • For API Key connectivity, the endpoint format is <region>.<cloud provider>.api.temporal.io:7233
    • Can be set using an environment variable
  • --namespace: Provide the namespace.accountId that appears at the top of the Namespace page in the UI.
    • Format is <namespace.accountId>
    • Can be set using an environment variable
  • --grpc-meta "temporal-namespace=": Provide the namespace.accountId again as grpc-metadata
  • --tls for a secure connection with the appropriate options
    • With --tls-disable-host-verification to disable host verification
    • Can be set using an environment variable

Here's an example of connecting 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.accountid> \
--tls --tls-disable-host-verification \
--grpc-meta "temporal-namespace=<namespace.accountid>"

SDK​

To use your API Key with a Temporal SDK, use headers to specify a Bearer token is provided for authentication and the Namespace for request routing. Temporal will simplify this experience for users to reduce the use of headers in subsequent SDK release.

Go SDK (v 1.26.0+)

Initial connection:

clientOptions := client.Options{
    HostPort: <endpoint>,
    Namespace: <namespace.accountid>,
    Credentials: client.NewAPIKeyStaticCredentials(<API Key>),
    ConnectionOptions: client.ConnectionOptions{
        TLS: &tls.Config{
            InsecureSkipVerify: true, // not recommended for production
        },
        DialOptions: []grpc.DialOption{
            grpc.WithUnaryInterceptor(
                func(ctx context.Context, method string, req any, reply any, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
                    return invoker(
                        metadata.AppendToOutgoingContext(ctx, "temporal-namespace", <namespace.accountid>),
                        method,
                        req,
                        reply,
                        cc,
                        opts...,
                    )
                },
            ),
        },
    },
}
c, err := client.Dial(clientOptions)

Update API key:

// Assuming client Credentials created with
var myKey string
creds := client.NewAPIKeyDynamicCredentials(
    func(context.Context) (string, error) { return myKey, nil })
// Just update by replacing
myKey = myKeyUpdated

Go SDK (pre v 1.26.0)​

Initial connection:

// Create headers provider
type APIKeyProvider struct {
    APIKey string
    Namespace string
}

func (a *APIKeyProvider) GetHeaders(context.Context) (map[string]string, error) {
    return map[string]string{"Authorization": "Bearer " + a.APIKey, "temporal-namespace": a.Namespace}, nil
}

// Use headers provider
apiKeyProvider := &APIKeyProvider{APIKey: <APIKey>, Namespace: <namespace.accountid>}
c, err := client.Dial(client.Options{
    HostPort: <endpoint>,
    Namespace: <namespace.accountid>,
    HeadersProvider: apiKeyProvider,
    ConnectionOptions: client.ConnectionOptions{TLS: &tls.Config{
        InsecureSkipVerify: true, // not recommended for production
    }},
})

Update API key:

apiKeyProvider.APIKey = myKeyUpdated

Java SDK​

At a client level:

// Create a Metadata object with the Temporal namespace header key.
Metadata.Key<String> TEMPORAL_NAMESPACE_HEADER_KEY =
    Metadata.Key.of("temporal-namespace", Metadata.ASCII_STRING_MARSHALLER);
Metadata metadata = new Metadata();
metadata.put(TEMPORAL_NAMESPACE_HEADER_KEY, <namespace.accountid>);

// Create the Workflow service stub.
WorkflowServiceStubsOptions.Builder stubOptions =
    WorkflowServiceStubsOptions.newBuilder()
        .setChannelInitializer(
            (channel) -> {
                channel.intercept(MetadataUtils.newAttachHeadersInterceptor(metadata));
            })
        .addGrpcMetadataProvider(
            new AuthorizationGrpcMetadataProvider(() -> "Bearer " + <APIKey>))
        .setTarget(<endpoint>);

// Not recommended for Prod use, ignore TLS verification
stubOptions.setSslContext(SimpleSslContextBuilder.noKeyOrCertChain().setUseInsecureTrustManager(true).build());

WorkflowServiceStubs service = WorkflowServiceStubs.newServiceStubs(stubOptions.build());

/*
 * Get a Workflow service client which can be used to start, Signal, and Query Workflow Executions.
 */
WorkflowClient client =
    WorkflowClient.newInstance(
        service, WorkflowClientOptions.newBuilder().setNamespace(<namespace.accountid>).build());

At a per-call level:

String myKey = "Bearer " + <APIKey>;
WorkflowServiceStubsOptions stubOptions =
    WorkflowServiceStubsOptions.newBuilder()
        .addGrpcMetadataProvider(new AuthorizationGrpcMetadataProvider(() -> myKey))
        .build();

// Just update by replacing, this must be done in a thread safe way
myKey = "Bearer " + <new APIKey>;

Python SDK (v 1.6.0+)​

Initial connection:

client = await Client.connect(
    <endpoint>,
    namespace=<namespace.accountid>,
    rpc_metadata={"temporal-namespace": <namespace.accountid>},
    api_key=<APIKey>,
    tls=True,
)

Update API key (newer SDK):

my_client.api_key = my_key_updated

Python SDK (pre v 1.6.0)​

Initial connection:

client = await Client.connect(
    <endpoint>,
    namespace=<namespace.accountid>,
    rpc_metadata={"temporal-namespace": <namespace.accountid>, "Authorization": f"Bearer {<APIKey>}"},
    tls=True,
)

Update API key:

my_client.rpc_metadata = {"Authorization": f"Bearer {<my_key_updated>}"}

.NET SDK (v 1.1.0+)​

Initial connection:

var myClient = TemporalClient.ConnectAsync(new(<endpoint>)
{
    Namespace = <namespace.accountid>,
    ApiKey = <APIKey>,
    RpcMetadata = new Dictionary<string, string>()
    {
        ["temporal-namespace"] = "${<namespace.accountid>}",
    },
    Tls = new(),
});

Update API key:

myClient.Connection.ApiKey = myKeyUpdated;

.NET SDK (pre v 1.1.0)

Initial connection:

var myClient = TemporalClient.ConnectAsync(new(<endpoint>)
{
    Namespace = <namespace.accountid>,
    RpcMetadata = new Dictionary<string, string>()
    {
        ["Authorization"] = $"Bearer {<APIKey>}",
        ["temporal-namespace"] = "${<namespace.accountid>}",
    },
    Tls = new(),
});

Update API key:

myClient.Connection.RpcMetadata = new Dictionary<string, string>()
{
    ["Authorization"] = $"Bearer {myKeyUpdated}",
};

Managing API Keys for Service Accounts​

Global Administrators have ability to manage API Keys for any Service Account in their Temporal Cloud Account. The process to manage API Keys for Service Accounts is very similar to the process of managing API Keys for Users with one difference: Unlike User API Keys, Global Admins are able to generate API Keys for Service Accounts. Disabling/enabling, deleting, and viewing API Keys for Service Accounts follows the same process as API Keys for Users.

Create an API Key for a Service Account​

Create an API Key for a Service Account using the Temporal Cloud UI or tcld.

Using the Cloud UI​

  1. Navigate to https://cloud.temporal.io/settings/identities
  2. Click the Create API Key button
  3. Click Service Account at the top of the page under "Create an API Key for*"
  4. Select the Service Account you would like to create an API Key in the “Mapped to identityˮ input box. Existing Service Accounts are provided in the “Mapped to Identityˮ box.
  5. Add values for the API Key. This includes:
  • name (required)
  • description (optional)
  • Expiration date (required - defaulted to 30 days)
  • The current max expiration duration for API Keys is 90 days.
  1. Click the Generate API Key button
  2. You will see the new API keyʼs secret, if the API Key was created successfully. Copy and store the secret somewhere safe.

Using tcld​

To create an API Key for a Service Account, use tcld apikey create with the --service-account-id flag:

tcld apikey create -n saAK1 --desc "Service Account API Key" --duration 30d --service-account-id "2f68507677904e09b9bcdbf93380bb95"

API Keys for Service Accounts appear in the list of API Keys in the UI and tcld.

Update an API Key for a Service Account​

Global Administrators have ability to disable/enable individual API Keys for any user in their account using the Cloud UI or tcld.

Using the Cloud UI​

  1. Navigate to https://cloud.temporal.io/settings/identities
  2. Find the identity that owns the API Key to disable/enable
  3. Click the Disable/Enable button to perform the desired action. There may be a delay after changing the status of an API Key.
  4. Once successful, the API Keys status will be reflected in the row.

Using tcld​

Use the tcld apikey disable or tcld apikey enable command, to disable or enable an API Key.

The process for enabling/disabling an API Key is the same for a User or a Service Account.

Delete an API Key for a Service Account​

Global Administrators have ability to delete individual API Keys for any user in their account using the Cloud UI or tcld.

Using the Cloud UI​

  1. Navigate to https://cloud.temporal.io/settings/identities
  2. Find the identity that owns the API Key to disable/enable and click on the row to see the API Keys associated with the identity.
  3. Click the Delete button. There may be a delay after changing the status of an API Key.
  4. Once successful, the API Keys status will be reflected in the row.

Using 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 a Service Account.

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