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 and the installation guide.

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.

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:

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:

bindplane get project 01ARZ3NDEKTSV4RRFFQ69G5FAV -o yaml > project.yaml

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.

3. Edit the secret key

Open project.yaml and set spec.secretKey to the new value:

apiVersion: bindplane.observiq.com/v1
kind: Account
metadata:
    id: 01ARZ3NDEKTSV4RRFFQ69G5FAV
    displayName: Your Project Name
spec:
    secretKey: NEW_SECRET_KEY_HERE

4. Apply the change

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:

spec:
    secretKey: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d

to this, where the former primary stays valid as an alternate:

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):

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 <key>	Make an existing key the default.
bindplane secret delete <key>	Remove a secret key.
bindplane secret rename <key> <name>	Set or update a key's name.

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.