Skip to main content

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.

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 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

ProblemWithout KnoxCallWith KnoxCall
Engineers share a Slack-pinned prod_passwordAnyone who joins/leaves the team triggers a rotationEach engineer mints their own 1-hour credential
CI pipeline holds a service-account secretLeak = full DB compromise until rotationLeak = ≤ TTL until auto-revoke
Audit trail of “who ran what against prod”Best-effort, by IPPer-credential, per-lease, in audit log
Onboarding a contractor for 2 weeksManual create + reminder to deleteSet 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.
  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, 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. 
# 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

EngineAPI valueDirectAgent tunnelSSH tunnelIAM (RDS)
PostgreSQLpostgres✅✅✅✅
MySQLmysql✅✅follow-up slice✅
MongoDBmongo✅✅follow-up slice❌ (not RDS)
See authentication modes for what each mode means and when to pick it.

​
Built-in role templates

TemplatePostgresMySQLMongoDB
readonlyGRANT SELECT ON ALL TABLESGRANT SELECTread role
readwriteGRANT SELECT, INSERT, UPDATE, DELETEGRANT SELECT, INSERT, UPDATE, DELETEreadWrite 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