Versioned, encrypted config.

Projects, environments, keys

Four levels, top to bottom:

• Project — one per app or service. Owns environments and the service tokens.
• Environment — dev, staging, prod, or whatever you name. This is the unit you pull and the unit a token is (optionally) pinned to.
• Key — env-var-style: ^[A-Z_][A-Z0-9_]*$. Each key is either static (a stored value) or dynamic (a leased credential).
• Version — every write to a static key creates a new immutable version and advances a current pointer.

Set, list, reveal

Writes require an admin or owner role. Listing shows keys and metadata but never values — the only way to see a plaintext is an audited get / reveal.

# Prompts for the value (hidden) if you omit --value.
tilldev secrets set STRIPE_KEY --env env_…
tilldev secrets set DATABASE_HOST --env env_… --value db.internal.example.com

# List keys + metadata (kind, current version, updated_at) — never values.
tilldev secrets ls --env env_…

# Reveal one value. This is an AUDITED read; --version defaults to current.
tilldev secrets get scr_… --version 2

Generate in the vault

set assumes you already have the value. But when a secret has to be created — a session secret, an HMAC key, a signing keypair — generating it with openssl or node -e on your laptop means the plaintext is born on a client and only then handed to the vault. secrets gen closes that gap: the value is minted server-side with node:crypto, sealed under your org DEK, and never returned. You can provision a credential without ever seeing it.

# MINT a value in the vault. The plaintext is generated server-side with
# node:crypto and NEVER returned — perfect for anything you'd otherwise pipe
# out of openssl/node and paste in (which puts the secret on your machine).
tilldev secrets gen SESSION_SECRET --env env_… --type random --bytes 32
tilldev secrets gen ADMIN_PASSWORD --env env_… --type password --length 40 --symbols
tilldev secrets gen WEBHOOK_HMAC   --env env_… --type hmac --encoding hex

# Keypairs: the PRIVATE half is sealed in the vault; only the PUBLIC half and the
# SSH fingerprint come back. Add --format jwk to store/return JWKs instead of PEM.
tilldev secrets gen DEPLOY_KEY  --env env_… --type ed25519
tilldev secrets gen JWT_SIGNING --env env_… --type rsa --rsa-bits 4096
# → Generated JWT_SIGNING → v1 — minted in the vault; the value never touched this machine

# Post-quantum keypairs work the same way.
tilldev secrets gen RELEASE_SIGNING_KEY --env env_… --type ml-dsa-65

# A TillForge token, straight into the vault (it acts with YOUR repo access).
tilldev secrets gen FORGE_TOKEN --env env_… --type forge-token \
  --repo api --scope write --expires 30

The post-quantum types, their formats and how to use them are in Post-quantum keys.

For a TillForge token that lives only as long as a job, use a forge_token backend instead: each lease mints a token that expires with the lease.

Immutable versions & rollback

A version is never edited or overwritten. Setting a key stores a new ciphertext under the next version number; the live value is whichever version the current pointer names. Rollback doesn’t restore or copy anything — it just moves that pointer to an older version, which is why it’s instant and lossless.

tilldev secrets versions scr_…
#  v3   2026-07-10   "rotate live key"   (current)
#  v2   2026-06-02   "promote staging"
#  v1   2026-05-11   "initial"

# Roll back = move the "current" pointer to an older, unchanged version.
tilldev secrets rollback scr_… --version 2

A soft-delete (secrets rm) removes a key from pulls but keeps every version, so a delete is auditable and recoverable. Nothing about a value’s history is destroyed by day-to-day use.

Sensitivity tiers

Every environment has a sensitivity from 0 to 10. A secret can have its own tier as well. The tier that applies is the higher of the two, and a secret with no tier of its own uses the environment’s. That lets one signing key in a busy environment be locked down without restricting everything around it.

# Tier a whole environment, or one secret in it.
tilldev secrets env update prod --sensitivity 8
tilldev secrets set STRIPE_SECRET_KEY --env prod --sensitive       # --sensitive = 7
tilldev secrets update STRIPE_SECRET_KEY --env prod --sensitivity 9
tilldev secrets update STRIPE_SECRET_KEY --env prod --sensitivity inherit

# A project-wide token gets the rest of the environment; restricted and sealed keys are withheld.
tilldev secrets pull --env prod
# error: withheld restricted or sealed key(s): STRIPE_SECRET_KEY — they need a token pinned to this environment
tilldev secrets pull --env prod --allow-partial   # warn and continue without them

From tier 7 up, a secret is restricted:

Service tokens & scopes

A ts_… service token is what a non-human client authenticates with. Each token is scoped to one project, carries a scope, and can optionally be pinned to one environment. It can also be given an expiry.

# read → pull only.  read_write → also lease and revoke dynamic credentials.
tilldev secrets tokens create --project prj_… --scope read --env env_…
tilldev secrets tokens create --project prj_… --scope read_write

# Per-key scope: pin the token to EXACTLY these keys (needs --env). The token can
# then pull ONLY these — nothing else in the environment. Ideal for a service that
# reads one signing key at boot.
tilldev secrets tokens create --project prj_… --env env_… \
  --keys TILLGATE_ATTEST_SIGNING_KEY

# --quiet: emit ONLY the raw token to stdout (confirmation goes to stderr) so it can
# be piped straight to the host that needs it — never rendered to a human screen.
tilldev secrets tokens create --project prj_… --env env_… \
  --keys TILLGATE_ATTEST_SIGNING_KEY --quiet | ssh host 'read T && install-token "$T"'

tilldev secrets tokens ls --project prj_…
tilldev secrets tokens revoke tok_… --project prj_…   # instant, irreversible

The pull endpoint

Everything above sits on top of one HTTP call. All the SDKs make it for you, but it’s plain enough to hit directly:

curl -X POST https://tilldev.dev/api/secrets/pull \
  -H "authorization: Bearer $TILLSECRETS_TOKEN" \
  -H "content-type: application/json" \
  -d '{}'   # env-pinned token. A project-scoped token sends {"environment_id":"env_…"}

# → {
#     "secrets": { "STRIPE_KEY": "sk_live_…", "DATABASE_HOST": "db.internal.example.com" },
#     "dynamic": [ "DATABASE_URL" ],
#     "withheld": []      # restricted or sealed keys this token may not read
#   }

It returns { secrets, dynamic, withheld }: the decrypted key→value map, the names of any dynamic keys in the environment (their values are leased, never returned here), and the names of restricted keys this token may not read. An env-pinned token needs no body; a project-scoped token must pass environment_id, and can only reach environments inside its own project.

With the x-tillsecrets-seal-key and x-tillsecrets-seal-nonce headers, the same object comes back encrypted to that key. The CLI and SDKs always send them; a token bound to a host key requires them. See the format.

The SDKs

Three packages, one client underneath:

The core client

import { SecretsClient } from '@tillstack/secrets-core'

const client = new SecretsClient({
  url: 'https://tilldev.dev',     // optional; this is the default
  token: process.env.TILLSECRETS_TOKEN!,
  environmentId: process.env.TILLSECRETS_ENV,  // only for project-scoped tokens
})

const { secrets, dynamic } = await client.pull()
const key = await client.get('STRIPE_KEY')     // convenience over pull()

Environment variables the Node SDK reads

• TILLSECRETS_TOKEN — the ts_… token. Required.
• TILLSECRETS_URL — API base. Optional; defaults to https://tilldev.dev.
• TILLSECRETS_ENV — environment id. Optional; only needed when the token is project-scoped rather than pinned to one environment.

load() follows dotenv’s rule — a variable already present in process.env is left alone unless you pass load({ override: true }). It throws when a restricted key is withheld from the token, unless you pass load({ allowPartial: true }).

Sync targets

Not every workload can call the pull API — a CI build, a serverless platform that only reads its own env vars, a container that boots before your code runs. For those, a sync target pushes an environment’s current values into the platform you already use. TillSecrets stays the source of truth; the platform just sees plain env vars.

The targets are vendor-agnostic:

Give a dotenv or custom target a secret and every push is signed in x-tillsecrets-webhook-signature: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 of t.raw_body with that secret, the same scheme as TillAuth webhooks. Check it over the raw body in constant time and refuse a t more than five minutes off, so a captured push can’t be replayed later to roll your values back. x-tillsecrets-signature: sha256=<hex> (the body alone, no timestamp) is still sent for receivers written before; it doesn’t stop a replay.

Each target’s credentials are encrypted at rest under the same per-org key as your secrets, and every push is written to the audit log as a sync.push. Configure targets from the dashboard under Secrets → Sync. The same environment can fan out to more than one target — no lock-in to any single platform.

Getting config into your app — pick your posture

There isn't one right way to hand a secret to a running service — it's a trade between simplicity, secret hygiene, and how much you want boot to depend on the vault. TillSecrets ships all three postures so you can choose per service, and even mix them:

# 1. On-disk — the platform holds env vars (simplest; secret lives in a file).
tilldev secrets pull --env env_… > .env         # or push via a sync target

# 2. Boot-time injection — the vault IS the manifest; nothing on disk.
TILLSECRETS_TOKEN=ts_… TILLSECRETS_URL=https://tilldev.dev \
  tilldev secrets exec --env prod -- node server.js

# 3. Selective in-app pull — the app fetches only what it needs, at runtime.
#    import { SecretsClient } from '@tillstack/secrets-core'
#    const signingKey = await client.get('JWT_SIGNING_KEY')

Deleting or rotating a TillDev token

Deleting a secret, or setting a new value, does not stop the old value working wherever it was issued. For a third-party key that is up to the vendor. For credentials TillDev issued, the vault can revoke them at the source: it decrypts each version server-side, recognises TillForge tokens (tfp_) and deploy tokens (tfd_), TillSecrets service and agent tokens (ts_, ta_), TillCache tokens (tc_) and API keys (tp_) that your org issued, and matches them by hash. The value never leaves the vault.

# Rotating a TillDev token: the new value replaces the old one, and the old token dies now.
tilldev secrets gen FORGE_TOKEN --env prod --type forge-token --repo api --scope write --revoke-previous
printf %s "$NEW_TOKEN" | tilldev secrets set CI_TOKEN --env prod --value-stdin --revoke-previous

# Deleting one: revoke what any version held, in the same call.
tilldev secrets rm FORGE_TOKEN --env prod --revoke-linked

# Look first, or clean up later.
tilldev secrets linked FORGE_TOKEN --env prod
tilldev secrets linked revoke FORGE_TOKEN --env prod          # only what older versions hold
tilldev secrets linked revoke FORGE_TOKEN --env prod --all    # the current value's too

• In a terminal, secrets rm, set and gen list any token that still works and ask whether to revoke it. Without a terminal they never revoke on their own: they warn and print the command.
• In the console, Delete shows the tokens with an also revoke box, and saving a new value offers to revoke the old one.
• A rotation revokes only what older versions hold. Setting the same token again is not a rotation.
• Each revocation is logged in the product that issued the token and as credential.revoke in the secrets audit log.