Quickstart: First Credential in ~10 Minutes

Deploy your webhook (Cloudflare Workers)

The reference webhook is TypeScript, runs on the Workers free tier, stores credentials in an auto-provisioned D1 database, and encrypts at rest with a key derived from one seed secret that never leaves your account.

git clone https://github.com/c-lgrant/tvault.git
cd tvault/examples/webhook
npm install

# Authenticate wrangler with your Cloudflare account (opens browser)
npx wrangler login

# Generate the root seed — an encrypted, write-only Workers Secret.
# Your AES key and HMAC secret are derived from it; Token Vault never has it.
openssl rand -hex 32 | npx wrangler secret put TV_WEBHOOK_SEED

# Deploy. The D1 database is auto-provisioned on first run.
npm run deploy

The deploy finishes with your webhook URL: https://<name>.<account>.workers.dev.

Bind the webhook to Token Vault

Binding is a one-time automatic handshake — you never copy an HMAC secret by hand.

1. Open https://<your-worker>.workers.dev/bind in a browser.
2. Click Connect to TokenVault. You're redirected to Token Vault (sign in with Google if prompted) with a one-time code.
3. Review the webhook URL and click Connect. Token Vault exchanges the code at your webhook's /v1/exchange endpoint and receives the HMAC secret directly from the webhook.

Your vault is now live, and Token Vault holds only its URL and the shared HMAC secret — no credentials, no encryption key.

Store a credential

In the dashboard, open Tokens → Add Custom Token. Paste any API key you want an agent to use — a GitHub personal access token is a good first test. Name the service github.

The browser sends the credential directly to your webhook with a signed store ticket; it never passes through Token Vault.

Give an agent access

1. Open Agents → New Agent, name it (e.g. quickstart-test), and copy the tvagent_… API key — it's shown once.
2. On the agent's page, grant it the github token with an expiry (1 hour is fine for a test).

Fetch the credential

curl -sL "https://api.tokenvault.uk/api/agents/credentials?service=github" \
  -H "Authorization: Bearer tvagent_YOUR_KEY"

{
  "token": {
    "accessToken": "ghp_…",
    "serviceName": "github",
    "tokenType": "pat",
    "createdAt": "2026-07-14T10:00:00Z"
  }
}

The -L matters: Token Vault validates the agent's key and policies, then answers with a 307 redirect to your webhook, which serves the credential straight to the agent. Token Vault's involvement ends at the redirect — it never sees the token.