Skip to main content

​
Lease lifetime

Every database credential KnoxCall mints is tracked as a lease. The lease records who got the credential, what role it was minted from, when it was issued, and — most importantly — when it expires. When the lease expires, KnoxCall automatically runs the role’s revocation_sql against the database and drops the user. The customer doesn’t have to remember to clean up.

​
Two TTL fields

Each connection (and each role) has two TTL settings:
  • Default TTL — the duration applied when the caller doesn’t ask for a specific TTL. Most “give me a credential” calls don’t specify, so this is the typical case.
  • Max TTL — the absolute ceiling. A caller can ask for less, but never more.
A request like POST /v1/dyn-db-credentials/{name}/creds/{role} with no ttl_seconds mints a 1-hour credential. A request asking for ttl_seconds=43200 (12h) mints a 12-hour credential. A request asking for ttl_seconds=172800 (48h) is silently clamped to the 24h ceiling — it doesn’t fail.

​
Resolution order

When a credential is minted, the TTL is resolved in this order:
  1. Caller-requested TTL (if provided and > 0).
  2. Role-level default (overrides connection default, if set).
  3. Connection-level default (the fallback).
Then the result is clamped to min(role.max_ttl, connection.max_ttl). So if you have connection.max_ttl=86400 and role.max_ttl=7200, the role-level cap wins — that role can never mint a credential longer than 2 hours, no matter what the caller asks for. This lets you define a strict role for prod (max_ttl=900 — 15 minutes) sitting on a connection with a more generous default (max_ttl=86400) used by other roles.

​
How revoke works

There are two paths to credential revocation:

​
1. Automatic (on expiry)

A background lease worker scans for expired leases on a regular tick. When it finds an expired lease, it calls the executor’s revoke() — which runs the role’s revocation_sql template substituted with the username — and flips the lease’s status to expired. You can see expired leases in the audit log: action db_credential.revoke with executor_ok: true.

​
2. Explicit (manual)

POST /v1/dyn-db-credentials/leases/{lease_id}/revoke (or click Revoke in the admin UI) does the same thing on demand. The lease ends up in revoked status rather than expired — useful for distinguishing “this was killed because someone leaked it” from “this aged out normally.”

​
IAM mode is special

For IAM mode, KnoxCall doesn’t create a dynamic DB user — it mints a 15-minute AWS auth token for an existing IAM-enabled user. There’s no DROP USER to run on revoke; the token simply stops working. Implications:
  • Lease TTL is capped at 15 minutes regardless of your default_ttl_seconds / max_ttl_seconds settings.
  • The lease worker still flips state at expiry for audit-trail completeness, but executor.revoke() is a no-op.
  • Explicit revoke also flips state but doesn’t actively kill the token — you can’t kill an AWS-signed token mid-flight; you wait for it to expire.
If you need fast kill-switch behaviour on RDS, layer on a security-group revoke or AWS IAM policy detach. KnoxCall’s lease state isn’t a substitute for those. Shorter is always safer. The friction cost of re-issuing is one API call.

​
Reading lease state in the UI

Open a connection on the Dynamic DB Credentials page to see its Live leases panel. Each row shows:
  • The minted username (also the lease’s subject ID — useful for grepping audit logs).
  • The role it came from.
  • When it expires.
  • A Revoke button.
The list shows every live lease — one whose database user still exists on your server. That means active, renewing and errored. Once a lease moves to expired or revoked its user has been dropped, so it falls off this view but remains in audit history. errored is on the list deliberately, and it is the row to look at first: KnoxCall gave up renewing that lease after five consecutive failures, so nothing is refreshing or expiring it and the database user is probably still live. Revoke it to drop the user. It is also the reason a delete can be refused — a connection or role with a live lease returns 409 (see below), and errored counts.

​
Listing leases over the API

GET /v1/dyn-db-credentials/leases returns the same set the UI panel shows — live leases only, meaning status active, renewing or errored. A lease that has expired or been revoked no longer has a database user, so it is neither listed nor counted in total; its history stays in the audit log. Each row names the database it belongs to: connection_name and engine come from the connection, role_name from the role it was minted from, and username is the account on the customer’s server.
connection is an exact match on the connection’s name and is scoped to the calling key’s Live/Test space — a tk_test_ key never sees a Live lease, and never sees one by naming a Live connection. Pagination is limit/offset, and both, along with total, are returned inside data.

​
”has N active credential lease(s)” — deleting a connection or role

Deleting a connection or a role is refused while any of its leases is live:
This is on purpose. Revoking a credential means DROP USER on your database, and reaching it needs the connection’s host and admin credential — or, for a role, its revocation SQL template. Delete those first and the leftover database users are stranded with nothing left that can drop them. The N in that message is exactly the set this page lists. It is the same definition of live — active, renewing, errored — used by the delete check, the UI panel and GET /v1/dyn-db-credentials/leases, so anything blocking your delete is visible with a Revoke button next to it. Revoke them, then retry the delete.