Recovery Keys

What should you do if you're locked out of your Seq instance? Perhaps your identity provider client secret expired, you fumbled an admin password change, or the only user with an admin password for Seq left without a forwarding address?

The best way to prepare for these scenarios is to generate a recovery key, and store it in a safe (and very secure) place. A recovery key is a regular API key that has been granted system-level permissions. Using a recovery key in conjunction with the seqcli command-line client, you can create new accounts, reset an account password, or update identity provider settings, without logging into the Seq user interface.

📘

Recovering without a Recovery Key

If you're stuck needing to re-gain access to a Seq instance without a recovery key saved, use the instructions in the Recovering without a Recovery Key topic.

Generating a Recovery Key

To generate a recovery key, open Settings > API keys, and Add to create a new key.

On the edit form, select all of the available permissions from the Permissions drop-down:

Over time, the permissions required for various actions in Seq may change. Assigning all available permissions to the key will ensure that if any new permissions are added, the key will be migrated so that those are also granted to the key.

After clicking Save Changes, copy the generated API key token, and store this in a safe place. The token cannot be retrieved once the dialog is closed.

Using a Recovery Key

The easiest way to perform recovery using a recovery key is to specify it on the seqcli command-line. All seqcli commands for interacting with a Seq instance accept -s SERVER and -a API_KEY arguments.

For example, to update the OpenId Connect provider secret, use:

seqcli setting set \
  -s SERVER \
  -a RECOVERY_KEY \
  -n OpenIdConnectClientSecret \
  -v YOUR_SECRET

Some common seqcli commands to use with recovery are setting set (demonstrated above), user create, and user update.

See the extensive seqcli README for more information about seqcli.

Rotating Recovery Keys

If your organization has a policy of rotating all credentials on a particular schedule, you can apply this to recovery keys, even using automation and the recovery key to effect the rotation.

Manually

To manually rotate a recovery key, the best method is to find the existing key in Settings > API keys, and choose Clone from the buttons at the bottom of the edit form.

Once the new key has been created, and its token securely stored, return to the original key and delete it using the Remove button on the same edit form.

Automating with seqcli

The seqcli apikey create command can be used to create new recovery keys, and the seqcli apikey remove command used to decommission old ones.

Because apikey remove is easiest to call using the key title (-t TITLE), it's best to use a unique title for recovery keys when automation is desired.