> For the complete documentation index, see [llms.txt](https://docs.strongdm.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.strongdm.com/admin/networking/proxy-clusters/proxy-cluster-key-management.md).

# Proxy Cluster Key Management

Learn how to manage proxy cluster authentication keys with the StrongDM CLI.

## **Overview**

Proxy cluster authentication keys are the credentials that proxy workers use to authenticate with the StrongDM control plane. Proper key management is essential for maintaining security and supporting zero-downtime credential rotation.

Proxy cluster keys consist of two components:

* **Access Key**: A public identifier (prefixed with `pk-`) that identifies the key
* **Secret Key**: A confidential credential that proves authentication

Every proxy worker in a cluster must have the correct access key and secret key configured to connect to the control plane. Unlike individual user credentials, proxy cluster keys are shared across all workers within a cluster.

Up to four keys per cluster are supported, which enables the following:

* **Zero-downtime rotation**: Create a new key and update workers gradually before retiring the old key.
* **Temporary overlap**: Maintain multiple valid credentials during deployments or transitions.
* **Disaster recovery**: Keep a backup key configuration for quick recovery if the primary key is compromised.

## **Create Keys**

Use the `sdm admin proxy-cluster-keys create` CLI command (or the alias `sdm admin proxy-cluster-keys add`) to generate a new authentication key.

{% hint style="warning" %}
The secret key is shown only once in the output. You must save it immediately in a secure location—it cannot be retrieved later. If you lose the secret key, delete this key and create a new one.
{% endhint %}

### **Example Output**

```
SDM_PROXY_CLUSTER_ACCESS_KEY=pk-XXXXXXXXXXXXXX
SDM_PROXY_CLUSTER_SECRET_KEY=XXXXX...
The secret key is shown only once and cannot be retrieved later. Save it now.
```

Use the environment variables shown above to configure your proxy worker deployments.

## **List Keys**

Use `sdm admin proxy-cluster-keys list` to view all active authentication keys for a proxy cluster. The output shows the following:

* **Access Key**: The public key identifier
* **Proxy Cluster ID**: The cluster this key belongs to
* **Created At**: When the key was created
* **Last Used At**: When this key was last used for authentication (helps identify unused keys)

This is useful for auditing which keys are in use and identifying candidates for removal.

## **Rotate Keys**

**Planned rotation** (recommended approach):

1. Create a new key: `sdm admin proxy-cluster-keys create <cluster-name>`.
2. Save the new access and secret keys securely.
3. Update your proxy worker deployments with the new credentials:
   * Update your Kubernetes manifests, Helm values, or deployment configurations.
   * Redeploy proxy workers.
   * Verify workers have restarted and are connecting with the new credentials.
4. Monitor the "Last Used At" timestamp to confirm the old key is no longer in use.
5. Delete the old key: `sdm admin proxy-cluster-keys delete <old-access-key>`.&#x20;

### **Emergency Rotation** (Compromised Key)

1. Immediately create a new key: `sdm admin proxy-cluster-keys create <cluster-name>`.
2. Update and redeploy all proxy workers with the new credentials.
3. Delete the compromised key: `sdm admin proxy-cluster-keys delete <compromised-access-key>`.

StrongDM cluster authentication is checked on every connection attempt, so workers using the old key will fail to connect once it's deleted.

## **Delete Keys**

Use `sdm admin proxy-cluster-keys delete` to remove an authentication key from the cluster.

{% hint style="warning" %}
Ensure no proxy workers are actively using this key before deletion. Any workers still configured with a deleted key will fail to authenticate with the control plane and will not be able to proxy connections.
{% endhint %}

You can verify that a key is not in use by checking the "Last Used At" timestamp—if it hasn't been used recently, it's safe to delete.

## **Monitoring and Auditing**

**Track key usage**:

* List keys regularly: `sdm admin proxy-cluster-keys list <cluster-name>`
* Review the "Last Used At" field to identify stale keys
* Schedule periodic key rotation (e.g., quarterly) to maintain security

**Audit trails**:

* Changes to proxy cluster keys are recorded in StrongDM audit logs
* Monitor for unexpected key creation or deletion events

**Best Practices**

1. **Secure Storage**: Store proxy cluster secret keys in your organization's credential management system (e.g., Kubernetes secrets, HashiCorp Vault, AWS Secrets Manager). Never commit them to version control.
2. **Principle of Least Privilege**: Limit access to proxy cluster keys to the minimal set of personnel who manage proxy infrastructure.
3. **Rotation Schedule**: Establish a regular key rotation schedule (e.g., quarterly) regardless of whether you suspect compromise.
4. **Monitor Usage**: Regularly check which keys are actively in use via the `list` command to identify unused credentials.
5. **Gradual Deployment**: When rotating keys, update proxy workers in batches to ensure no disruption to client connections.
6. **Overlap Window**: Always create the new key before deleting the old key, maintaining an overlap window during worker updates.
7. **Documentation**: Document which proxy clusters use which keys, and when key rotations occur, for compliance and audit purposes.

## **Related Topics**

* **Proxy Clusters**: Overview of proxy cluster architecture and deployment
* **Bridged Proxy Clusters**: Advanced proxy cluster configurations
* **CLI Commands**:
  * `sdm admin proxy-cluster-keys`
  * `sdm admin proxy-cluster-keys create`
  * `sdm admin proxy-cluster-keys list`
  * `sdm admin proxy-cluster-keys delete`

## **Troubleshooting**

### **Proxy Workers Fail to Connect After Key Deletion**

If workers stop connecting after you delete a key, they may still be configured with the old credentials:

1. Verify the workers are using the correct access and secret keys
2. Check that your deployment manifests or configuration files have been updated
3. Ensure workers have been restarted with the new configuration
4. Check logs for authentication errors

### **Lost Secret Key**

If you lose a secret key:

1. Delete the key pair using the access key identifier: `sdm admin proxy-cluster-keys delete <access-key>`
2. Create a new key: `sdm admin proxy-cluster-keys create <cluster-name>`
3. Update worker deployments with the new credentials
4. Redeploy workers

### **Maximum Key Limit Is Reached**

If you hit the four-key limit:

1. List all keys to identify which ones are no longer in use: `sdm admin proxy-cluster-keys list <cluster-name>`.
2. Delete unused keys: `sdm admin proxy-cluster-keys delete <access-key>`.
3. Create your new key: `sdm admin proxy-cluster-keys create <cluster-name>`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.strongdm.com/admin/networking/proxy-clusters/proxy-cluster-key-management.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
