> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/how-to-guides/infrastructure-and-operations/change-project-secret-key.md). # Change a Project Secret Key Each Bindplane project has a secret key that clients use to authenticate with it. You may need to change that key, for example to rotate a credential on a schedule or to replace one that has been exposed. This guide covers changing the key directly and rotating keys with no downtime. All steps use the `bindplane` CLI. If you are new to it or do not have it installed, see the [Bindplane CLI documentation](/cli-and-api/cli.md) and the [installation guide](/cli-and-api/cli/installation.md). {% hint style="warning" %} Replacing the default secret key takes effect immediately. Any collector or client still using the old key will fail to authenticate until it is updated. To rotate without an outage, keep the old key valid as an *alternate* while you move clients to the new key, then delete the old key. See [Rotate keys with no downtime](#rotate-keys-with-no-downtime). {% endhint %} ### Change a project's secret key #### 1. Find the project ID List your projects and locate the one you want by its display name. The `id` is on the line above its `displayName`: ```bash bindplane get project | grep -B1 "Your Project Name" ``` ``` id: 01ARZ3NDEKTSV4RRFFQ69G5FAV displayName: Your Project Name ``` You can also find the project ID in the Bindplane UI. #### 2. Export the project to YAML Write the project's full resource to a file, using the ID from the previous step: ```bash bindplane get project 01ARZ3NDEKTSV4RRFFQ69G5FAV -o yaml > project.yaml ``` {% hint style="warning" %} Do not add the `--export` flag here. The exported form drops fields that are required to apply the resource back to the same project, so you will not be able to re-apply it. {% endhint %} #### 3. Edit the secret key Open `project.yaml` and set `spec.secretKey` to the new value: ```yaml apiVersion: bindplane.observiq.com/v1 kind: Account metadata: id: 01ARZ3NDEKTSV4RRFFQ69G5FAV displayName: Your Project Name spec: secretKey: NEW_SECRET_KEY_HERE ``` #### 4. Apply the change ```bash bindplane apply -f project.yaml ``` #### Full example ``` $ bindplane get project | grep -B1 "Example Project" id: 01ARZ3NDEKTSV4RRFFQ69G5FAV displayName: Example Project $ bindplane get project 01ARZ3NDEKTSV4RRFFQ69G5FAV -o yaml > project.yaml $ code project.yaml $ bindplane apply -f project.yaml Account 01ARZ3NDEKTSV4RRFFQ69G5FAV unchanged ``` (The example reports `unchanged` because no edit was made to the file. After a real edit to `spec.secretKey`, it reports `configured`.) ### Rotate keys with no downtime A project can have more than one valid secret key at a time: the default key in `spec.secretKey`, plus any number of keys in `spec.alternateSecretKeys`. Every listed key authenticates, so you can stand up a new key while the old one still works, then retire the old key once nothing uses it. Secret keys are ULIDs. Projects created before Bindplane moved to ULIDs may still carry UUID-format keys, which remain valid. Rotating off a legacy key uses the same overlap process. Rotate in three steps: 1. **Move the current primary key into the alternates,** where it stays valid. 2. **Create a new primary key** in `spec.secretKey`. 3. **Later, once your collectors and clients are using the new key, delete the old key from the alternates.** Steps 1 and 2 are a single change: edit the YAML so the old `secretKey` value moves into `alternateSecretKeys` and the new value becomes `secretKey`. Then apply. `bindplane secret add --default` does the same thing in one command, generating the new key, promoting it to the default, and demoting the old default into the alternates. Use the YAML workflow when the new primary needs to be a *specific* value rather than a generated one. Steps 1 and 2 move the spec from this: ```yaml spec: secretKey: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d ``` to this, where the former primary stays valid as an alternate: ```yaml spec: secretKey: 01HQ8XN5K2J7P4M9TVWZ3RBCDE alternateSecretKeys: - a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d ``` After step 3, the old key is removed (run `bindplane secret delete a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d`, or drop it from `alternateSecretKeys` and apply): ```yaml spec: secretKey: 01HQ8XN5K2J7P4M9TVWZ3RBCDE ``` ### The `bindplane secret` commands Bindplane also ships dedicated commands for managing the secret keys of the current project: | Command | Description | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `bindplane secret get` | List the project's secret keys. Use `-n` to filter by name and `-o json\|yaml\|table` for the output format. | | `bindplane secret add` | Generate a new secret key and add it to the project. Pass `--default` to promote it to the default key, and `-n` to store a name. | | `bindplane secret default ` | Make an existing key the default. | | `bindplane secret delete ` | Remove a secret key. | | `bindplane secret rename ` | Set or update a key's name. | {% hint style="info" %} `bindplane secret add` **generates** a brand new random key. It does not let you set a specific value. When you need a key to be a particular value (for example, a value supplied by your secrets manager), use the export, edit, and apply workflow above instead. {% endhint %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bindplane.com/how-to-guides/infrastructure-and-operations/change-project-secret-key.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.