> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcphub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Credential Key Upgrade and Recovery

> Preserve your key during upgrades and reset personal bindings if the key is lost

**The database stores encrypted credentials, not their encryption key. Preserve the original key during upgrades; if it is permanently lost, users must bind again.** This guide covers personal credentials and personal upstream OAuth.

Database mode no longer generates a local key automatically. Without `MCPHUB_CREDENTIAL_ENCRYPTION_KEY` or an existing valid `.credentials.key` file, binding saves fail, but the service can still start. Environment keys take precedence over files. Existing files remain supported; JSON mode still supports automatic key generation.

## Choose your path

| Current state | Action |
| - | - |
| Working with an environment key | Preserve its exact value during the upgrade. |
| Working with a local key file | Back it up before removing the container and configure its value as the environment key. |
| Upgrade failed; original key is available | Restore the original key and restart. |
| Original key is permanently lost | Configure a new key and reset bindings individually or in bulk. |
| No personal bindings yet | Generate a key once and persist it before use. |

## Working deployment: preserve the key

1. Back up the database and key separately. Keep the old container until verification is complete.
2. Preserve the existing environment key. If using a file, copy it from the old container and configure its Base64 value as `MCPHUB_CREDENTIAL_ENCRYPTION_KEY`. **Do not generate a replacement key.**
3. Upgrade the image, retaining other deployment settings. All instances sharing the database must use the same key.
4. Verify MCP calls with existing bindings, personal OAuth connections, and new binding saves.

Copy the key from the current Docker default path:

```bash theme={null}
mkdir -m 700 ./mcphub-key-backup
docker cp mcphub:/app/data/mcp_settings.json.credentials.key ./mcphub-key-backup/credentials.key
chmod 600 ./mcphub-key-backup/credentials.key
```

The filename is the effective settings path plus `.credentials.key`. Legacy deployments may use `/app/mcp_settings.json.credentials.key`; custom deployments follow `MCPHUB_SETTING_PATH`. Adjust the container name and path. Stopped containers can also be copied from until removed. Adding a directory mount does not migrate the existing file.

Add this entry to the existing Compose service's `environment` mapping:

```yaml theme={null}
environment:
  MCPHUB_CREDENTIAL_ENCRYPTION_KEY: ${MCPHUB_CREDENTIAL_ENCRYPTION_KEY:?Set the persistent credential encryption key}
```

Supply the original value through your deployment platform or an access-restricted, untracked Compose `.env` file. For `docker run`, use `--env-file` with `MCPHUB_CREDENTIAL_ENCRYPTION_KEY=<original-base64-value>`. Keep the key outside the container for future deployments.

## Upgrade failed: original key is available

Pause binding changes and recover the key from the previous environment configuration, old container, mounted directory, or backup. Restore its value as `MCPHUB_CREDENTIAL_ENCRYPTION_KEY` on every instance, restart, and verify MCP calls. Alternatively, restore the original key file with mode `0600` and persist its directory; remove any incorrect environment override.

The original key restores bindings encrypted with it. Any bindings saved with another key during recovery must be replaced or reauthorized.

## Original key lost: reset bindings

**A new key cannot decrypt old data. Rolling back the image or restoring only the database will not help.** Back up the database, then choose one of the following options.

Generate a new key once, save it in deployment secrets, and configure the same `MCPHUB_CREDENTIAL_ENCRYPTION_KEY` on every instance. If a new persistent key is already configured, retain it:

```bash theme={null}
openssl rand -base64 32
```

### Option 1: users replace their own bindings

Configure the new key and restart all instances. Users must submit all personal credential values again, or delete the old binding first. Personal OAuth users must disconnect and authorize again. Verify tool calls afterward.

If the dashboard cannot load the old binding, use these APIs to delete the current user's binding, then bind again:

| Type | Endpoint |
| - | - |
| Personal credentials | `DELETE /api/credentials/:name` |
| Personal OAuth | `DELETE /api/servers/:name/oauth/personal` |

Use dashboard authentication and URL-encode the server name. MCP bearer keys cannot manage bindings. An administrator's session also acts only on that administrator's own bindings.

### Option 2: administrator clears all bindings

Use this when all users will bind again. **This deletes every user's personal credentials, personal OAuth tokens, client registration data, and pending flows in the table, including any bindings already restored.** User accounts and server definitions are unaffected.

1. Stop all MCPHub instances sharing the database to prevent concurrent writes and clear cached runtimes. Direct SQL does not emit application invalidation events.
2. Back up the database, confirm the target database and schema, and inspect `SELECT COUNT(*) FROM credential_bindings;`.
3. Run the following SQL and check that no rows remain:

   ```sql theme={null}
   BEGIN;
   DELETE FROM credential_bindings;
   SELECT COUNT(*) AS remaining_bindings FROM credential_bindings;
   ```

   Execute `COMMIT;` separately after checking, or `ROLLBACK;` if anything is unexpected. Keep the table structure. After commit, restoring rows requires a backup; decrypting them still requires the original key.
4. Confirm every instance has the same persistent key, then start the service. **An empty table does not re-enable automatic key generation.**
5. All users must enter personal credentials or authorize OAuth again, then verify tool calls.

Neither reset option can revoke old OAuth tokens that cannot be read. Users should revoke obsolete grants through the upstream service when needed.

## Future backups

Back up the database and key separately. Preserve the key during upgrades, scaling, and migration. Normal configuration exports exclude personal bindings and the key.

In JSON mode, persist the settings file and its `.credentials.json` and `.credentials.key` files, or use a persistent environment key. See [Docker Setup](https://docs.mcphub.app/configuration/docker-setup.md) and [Per-user Credentials](https://docs.mcphub.app/features/per-user-credentials.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.