Skip to main content

​
Creating an API key

  1. Go to Settings in the sidebar
  2. Click Create Key
  3. Enter a label (e.g., “CI/CD pipeline”, “Monitoring script”)
  4. Choose a scope
  5. Copy the key immediately
API key creation requires a Pro or Business plan. Free users will see an upgrade prompt instead of the create form.
Each full API key secret is shown only once when created or replaced. DBHost stores only a hash plus the visible prefix, so the current secret cannot be recovered later. Save it in a secure location.

​
Key scopes

  • Selected databases (Recommended) limits the key to only the databases you choose. It can list and manage only those databases.
  • Full account access can create and manage every database in your account.
Selected-database keys cannot create new databases. If your automation needs to provision databases, create a full-access key instead. Selected-database keys also follow least-privilege behavior in the API and CLI:
  • GET /api/v1/databases returns only the selected databases
  • Database-specific routes outside scope return DATABASE_NOT_FOUND
  • Full-account-only routes like database creation return KEY_SCOPE_DENIED
API key scope is immutable in v1. To change scope, revoke the key and create a new one.

​
Replacing a key

Click Replace key next to an existing key if you need a fresh secret without changing the label or scope bindings.
  • The old secret stops working immediately
  • The new secret is shown once right after replacement
  • The key keeps the same label and scope configuration

​
Safe rotation checklist

Replace key is an immediate cutover. Use it only when every consumer can be updated at the same time. If you need a zero-downtime rotation, create a second key with the same least-privilege scope, migrate the consumers, verify the new key, and then revoke the old key.
  1. Inventory every script, environment variable, CI job, and secret store that uses the current key.
  2. Prepare the destination for the new secret before creating or replacing the key.
  3. Copy the new secret immediately and update every consumer.
  4. Run a read-only command such as dbhost databases list from the real consumer environment.
  5. Revoke the old key if you used an overlapping second key, then remove the old secret from temporary notes and local shells.
If the required scope or selected-database bindings have changed, create a new key instead of using Replace key.

​
Using API keys

Include the key in the Authorization header:
Or use it with the CLI:

​
Key format

API keys have a visible prefix (e.g., dbh_abc1) for identification and a secret portion. In the settings page, you’ll see the prefix, label, scope, and last-used timestamp.

​
Revoking a key

Click Revoke next to any key in the settings page. The key stops working immediately.