Temporal Integration
Connect Temporal so agents can inspect your cluster with the Temporal CLI. Agents can:
- List workflows.
- Describe executions and read their history.
- Inspect task queues.
- List schedules.
Capabilities
Once connected, agents run read-only temporal commands, such as:
| Capability | Example Command |
|---|---|
| List Workflows | temporal workflow list --namespace prod |
| Describe Workflow | temporal workflow describe --workflow-id my-wf |
| Get Workflow History | temporal workflow show --workflow-id my-wf |
| List Task Queues | temporal task-queue describe --task-queue my-queue |
| List Schedules | temporal schedule list --namespace prod |
| Describe Namespace | temporal operator namespace describe --namespace prod |
Commands that change workflow state, such as start, signal, cancel, terminate and reset, are classified as writes. Agents are instructed not to run them, and a governance policy on write operations pauses any such call for a person to approve. Use a read-only credential (below) so the cluster itself refuses them.
Prerequisites
- A Temporal cluster (Temporal Cloud or self-hosted)
- One of the supported authentication methods configured
- Namespace access
Setup
Go to Integrations in Autoheal and click Temporal.
Choose your authentication method from the dropdown:
- Cloud (API Key) — For Temporal Cloud with API key authentication
- Cloud (mTLS) — For Temporal Cloud with mutual TLS certificates
- Direct Connect — For any Temporal server by address, with optional mTLS
Fill in the required fields based on your selected auth method (see details below).
Enter a name for the integration (e.g., "Production Temporal") and click Save.
Authentication Methods
Cloud (API Key)
For Temporal Cloud clusters using API key authentication. This is the recommended method for Temporal Cloud.
| Field | Description | Example |
|---|---|---|
| Default Namespace | Your Temporal namespace | quickstart-vishal |
| Account ID | Your Temporal Cloud account ID | tukws |
| Region (advanced) | Optional. Pins the connection to a single region's gRPC endpoint. Leave blank in almost all cases. | us-west-2.aws |
| API Key | Temporal Cloud API key | tmprl_... |
By default, API-key connections use the recommended per-namespace endpoint {namespace}.{account_id}.tmprl.cloud:7233. This endpoint supports API keys and automatically follows High Availability failover to the active region. Leave Region blank unless you have a specific reason to pin traffic to one region. If you set Region, the connection uses the regional gRPC endpoint {region}.api.temporal.io:7233 (for example, us-west-2.aws.api.temporal.io:7233) instead. The regional endpoint does not follow HA failover. The namespace is passed separately as {namespace}.{account_id}.
One exception applies if your namespace has both API key and mTLS authentication enabled (Temporal's pre-release dual-auth mode). In that mode, the per-namespace endpoint cannot authenticate an API key. Set Region so the connection uses the regional endpoint, or use the Cloud (mTLS) method instead.
Find your Account ID in your namespace URL: https://cloud.temporal.io/namespaces/{namespace}.{account_id}.
Leave Region blank unless you specifically need to pin to one region. The default per-namespace endpoint already reaches your namespace and follows HA failover. If you do pin, find the <region>.<cloud> value in the Temporal Cloud console under the namespace's connection details (e.g. us-west-2.aws, eu-central-1.aws, us-central1.gcp).
Generate an API key from an account-level Service Account in Temporal Cloud Settings to access all namespaces with a single integration.
The target namespace must also permit API key authentication. In the Temporal Cloud console, a namespace has to be configured with "Allow API key authentication". This is a namespace-level setting, separate from account-level key management. Account owners enable or disable creating keys under Settings → API Keys. That setting does not by itself make a certificate-only namespace accept keys.
If a namespace is not configured to allow API keys, it stays mTLS-only and rejects the connection with tls: certificate required. Either enable "Allow API key authentication" on that namespace, or use the Cloud (mTLS) method with a client certificate instead.
Cloud (mTLS)
For Temporal Cloud clusters using mutual TLS certificate authentication.
| Field | Description |
|---|---|
| Default Namespace | Your Temporal namespace |
| Account ID | Your Temporal Cloud account ID |
| TLS Certificate | Client TLS certificate in PEM format |
| TLS Private Key | Client TLS private key in PEM format |
Before you connect with mTLS, upload your CA certificate to the Temporal Cloud namespace in the Temporal Cloud console.
Direct Connect
For any Temporal server you can reach by address — on-prem, private cloud, BYOC, or any other deployment. Optionally provide TLS certificates if your server enforces mutual TLS.
| Field | Description | Example |
|---|---|---|
| Default Namespace | Your Temporal namespace | default |
| Temporal Host | Server address with port | temporal.internal:7233 |
| TLS Certificate | (Optional) Client TLS certificate in PEM format | |
| TLS Private Key | (Optional) Client TLS private key in PEM format | |
| Server CA Certificate | (Optional) Server CA cert in PEM format |
If your Temporal server does not require authentication, provide only the host and leave the TLS fields empty. If your server enforces mTLS, provide the client certificate and private key. The Server CA Certificate is only needed if your server uses a private CA not in the system trust store.
Multi-Namespace Support
The Default Namespace is used automatically for all commands. The agent can override it per-command using the --namespace flag:
List workflows in the staging namespace
The agent will run: temporal workflow list --namespace staging
For Temporal Cloud with API Key auth, a single integration can access all namespaces under the same account. Use an account-level Service Account API key for this.
Example Queries
Once connected, you can ask an agent questions like:
Show me all running workflows in the production namespace
What's the status of workflow payment-workflow-123?
Are there any stuck workflows? Check the task queue health.
List all schedules and check if any are paused
Show me the history of the last failed workflow
Required Permissions
| Permission | Why It's Needed |
|---|---|
| Namespace read | Access namespace information |
| Workflow read | View and list workflow executions |
| Task queue read | Monitor task queue status |
| Schedule read | Access scheduled workflows |
For security, create dedicated credentials for Autoheal with read-only permissions. Avoid using admin credentials.
Security Best Practices
- Use dedicated credentials: Create a separate API key or certificate pair for Autoheal
- Limit namespace access: Restrict access to only the namespaces needed
- Rotate credentials regularly: Update API keys and certificates on a regular schedule
- Prefer API Key for Cloud: API key auth is simpler and avoids certificate management overhead
Troubleshooting
Connection Refused
- Check that the host address and port are correct
- For Temporal Cloud, the address is auto-derived. Check that your Account ID and namespace are correct
- For self-hosted, check that the cluster is accessible from Autoheal
- Check network connectivity and firewall rules
Authentication Failed
- API Key: Check that the key is correct and not expired. If you access multiple namespaces, check that the key is from an account-level Service Account.
- mTLS (Cloud): Check that your CA certificate is uploaded to the namespace in the Temporal Cloud console
- mTLS (Direct Connect): Check that all certificates are in PEM format and not expired
Certificate Errors
- Check that certificates are in PEM format (start with
-----BEGIN CERTIFICATE-----) - Check that the client key matches the client certificate
- For self-hosted, check that the Server CA certificate is the root CA that signed the server certificate
tls: certificate required (with API Key auth)
The endpoint requires a client certificate. It rejects the API-key connection at the TLS handshake, before the key is ever examined. An invalid or mis-scoped key never causes this error. That problem surfaces later as an authentication error (see Authentication Failed). The cause is the namespace/endpoint combination. Two cases:
- Namespace doesn't allow API keys (most common): the namespace must have API key authentication enabled in the Temporal Cloud console. A certificate-only namespace always demands a client certificate and returns this error on every endpoint. Enable API keys on the namespace, or switch this integration to the Cloud (mTLS) method with a client certificate.
- Namespace has both API key and mTLS enabled (dual auth): Temporal's pre-release dual-auth mode does not support authenticating with an API key on the per-namespace endpoint. Set Region to your namespace's
<region>.<cloud>. The connection then uses the regional endpoint{region}.api.temporal.io:7233, which accepts the API key. Or, switch this integration to Cloud (mTLS).
On endpoints: leaving Region blank is right for the common cases. The default per-namespace endpoint {namespace}.{account_id}.tmprl.cloud:7233 accepts API keys for API-key-only namespaces. It also automatically follows High Availability failover. Only set Region for the dual-auth case above, or to deliberately pin to one region. A wrong Region does not produce this error. A wrong Region points the connection at {wrong-region}.api.temporal.io:7233. That address fails to resolve or returns a different error (namespace not found / unauthorized) instead.
Namespace Not Found
- Check that the namespace name is correct (case-sensitive)
- For Temporal Cloud, use the namespace name shown in the console (not the full address)
- Check that the API key has access to the target namespace