Hep.gg

API keys

How management API keys are minted, rotated, and revoked, where they come from, and how account suspension disables them.

API keys

The management API authenticates with a bearer key of the form hepgg_db_ followed by a random suffix. This page explains where those keys come from and how their lifecycle works.

Where keys come from

Open the Database app in the dashboard and go to the API Keys tab. Create a key there, optionally giving it a label. The full key value is shown when you create it; copy it then and store it somewhere safe. Treat it like a password: anyone holding it can list and create databases, and reveal or rotate your database passwords. Never commit it to source control or print it in logs.

What a key can do

A management key can:

  • List your databases (GET /api/v1/db/databases)
  • Create a database (POST /api/v1/db/databases)
  • Reveal a database's current password (GET /api/v1/db/databases/:id)
  • Rotate a database's password (POST /api/v1/db/databases/:id/rotate)

It cannot delete a database or manage other keys; those stay in the dashboard, gated behind your session. A leaked key therefore cannot destroy a database or touch your other keys, but it can read and change your database passwords, so treat it as a high-value secret and disable or rotate it from the dashboard if it is ever exposed.

How many keys you can have

Active-key limits follow your tier: Free allows 2 active keys, Premium allows 10. Disabling a key frees a slot; re-enabling one that would push you back over the limit is refused until you disable another.

Rotating and revoking

From the dashboard you can:

  • Rotate a key, which issues a new hepgg_db_ value for the same key record. The old value stops working immediately; update your scripts with the new value.
  • Disable a key, which keeps the record but stops it authenticating.
  • Delete a key, which removes it entirely.

A rotated, disabled, or deleted key fails the management API with 401. See the error catalog for the exact codes (BAD_KEY for a value that no longer matches, KEY_DISABLED for a disabled key).

Suspension disables every key

If your account is suspended, the suspension cascade disables all of your management keys at once. Every subsequent management-API call returns 401 KEY_DISABLED until the suspension is lifted. Your databases themselves also move to disabled status and their connection users are locked, so your databases are unavailable too. Re-enabling happens automatically when the suspension is cleared.