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

# Dynamic DB Credentials overview

> Mint short-lived database credentials on demand. Replaces long-lived service-account passwords with auth that auto-expires.

> **Renamed 2026-05-03.** This feature was previously called **Databases**.
> The old `/v1/databases/*` and `/admin/databases/*` paths now return 404 —
> use `/v1/dyn-db-credentials/*` and `/admin/dyn-db-credentials/*`.
> The "Databases" name has been freed for the upcoming **Database Proxy**
> product (a TCP-level Postgres / MySQL wire-protocol proxy — see the
> [Dynamic Credentials & Protocol Proxies design doc](https://github.com/knoxcall/knoxcall/blob/main/docs/internal/dynamic-credentials-and-protocol-proxies.md)
> for context).

# Dynamic DB Credentials overview

KnoxCall's **Dynamic DB Credentials** feature lets you mint short-lived database credentials on demand — for engineers, CI pipelines, scheduled jobs, or any workload that needs temporary DB access without sharing a long-lived password.

You register a database connection once. After that, callers ask KnoxCall for a credential whenever they need one. KnoxCall mints a fresh username + password (or an AWS auth token), tracks it as a **lease**, and automatically revokes it at expiry.

## Why use it

| Problem                                        | Without KnoxCall                                     | With KnoxCall                                   |
| ---------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------- |
| Engineers share a Slack-pinned `prod_password` | Anyone who joins/leaves the team triggers a rotation | Each engineer mints their own 1-hour credential |
| CI pipeline holds a service-account secret     | Leak = full DB compromise until rotation             | Leak = ≤ TTL until auto-revoke                  |
| Audit trail of "who ran what against prod"     | Best-effort, by IP                                   | Per-credential, per-lease, in audit log         |
| Onboarding a contractor for 2 weeks            | Manual create + reminder to delete                   | Set TTL = 14 days, drops itself                 |

## How it works

1. **Register a connection** — point KnoxCall at your database (Postgres, MySQL, or MongoDB). Pick one of four [authentication modes](/essentials/dyn-db-credentials/auth-modes).
2. **Define a role** — an SQL template that describes the kind of user to mint (read-only, read-write, or your own template). Built-in `readonly` / `readwrite` templates work for most setups.
3. **Mint a credential** — call `POST /v1/dyn-db-credentials/{name}/creds/{role}` with an API key. Get back a username + password + expiry.
4. **Use it** — connect with the returned credentials like any other DB user.
5. **Forget it** — at the [lease's expiry](/essentials/dyn-db-credentials/leases), KnoxCall drops the user automatically. Or revoke it explicitly with `POST /v1/dyn-db-credentials/leases/{id}/revoke`.

## Quick start (UI)

1. Go to **Dynamic DB Credentials** in the admin UI and click **New Connection**.
2. Fill in the connection details. **Test** the connection — KnoxCall verifies it can reach your DB before letting you save.
3. After creation, expand the connection and click **Register role** → pick `readonly` or `readwrite`.
4. Click **Mint credential** to issue your first short-lived user.

## Quick start (API)

All responses use the standard `{ data: ..., meta: { request_id: "..." } }` envelope. The examples below show the `data` fields.

```bash theme={"dark"}
# 1. Register (replace KC_API_KEY with your key)
curl -X POST https://api.knoxcall.com/v1/dyn-db-credentials \
  -H "Authorization: Bearer $KC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "postgres-prod",
    "engine": "postgres",
    "host": "db.example.internal",
    "port": 5432,
    "admin_username": "kc_admin",
    "admin_password": "...",
    "execution_mode": "direct",
    "default_ttl_seconds": 3600,
    "max_ttl_seconds": 86400
  }'

# 2. Register a role (built-in readonly template)
curl -X POST https://api.knoxcall.com/v1/dyn-db-credentials/postgres-prod/roles \
  -H "Authorization: Bearer $KC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "analytics_ro", "template": "readonly" }'

# 3. Mint a credential
curl -X POST https://api.knoxcall.com/v1/dyn-db-credentials/postgres-prod/creds/analytics_ro \
  -H "Authorization: Bearer $KC_API_KEY"
# → data: { "username": "kc_user_...", "password": "...", "expires_at": "...",
#           "lease_id": 42, "connection_name": "postgres-prod", "role_name": "analytics_ro" }
```

## Supported engines

| Engine     | API value  | Direct | Agent tunnel | SSH tunnel | IAM (RDS)   |
| ---------- | ---------- | ------ | ------------ | ---------- | ----------- |
| PostgreSQL | `postgres` | ✅      | ✅            | ✅          | ✅           |
| MySQL      | `mysql`    | ✅      | ✅            | ✅          | ✅           |
| MongoDB    | `mongo`    | ✅      | ✅            | ✅          | ❌ (not RDS) |

See [authentication modes](/essentials/dyn-db-credentials/auth-modes) for what each mode means and when to pick it.

## Built-in role templates

| Template    | Postgres                               | MySQL                                  | MongoDB          |
| ----------- | -------------------------------------- | -------------------------------------- | ---------------- |
| `readonly`  | `GRANT SELECT ON ALL TABLES`           | `GRANT SELECT`                         | `read` role      |
| `readwrite` | `GRANT SELECT, INSERT, UPDATE, DELETE` | `GRANT SELECT, INSERT, UPDATE, DELETE` | `readWrite` role |

Both templates create a user with the password KnoxCall generates and grant just enough permissions for the named scope. If neither fits, supply your own `creation_sql` + `revocation_sql`.

## Next steps

* [Authentication modes →](/essentials/dyn-db-credentials/auth-modes)
* [Lease lifetime →](/essentials/dyn-db-credentials/leases)
* [API reference →](/api-reference/overview)