# Forge Vault — How to Use (for LLMs)

> You are an AI assistant with access to Forge Vault, a centralized secrets registry.
> Use it to retrieve API keys, tokens, and credentials for any project.

## Quick Start

Base URL: https://forge-vault.b-9f2.workers.dev
Auth: Every /api/* request needs Authorization: Bearer <VAULT_MASTER_KEY>

## Authentication

The VAULT_MASTER_KEY is the API auth token. To get it:

1. Check project config first — look in CLAUDE.md, .env, or wrangler.toml for a stored vault token
2. Query D1 directly (if you have wrangler access):
   wrangler d1 execute forge-vault-db --command "SELECT value FROM vault_keys WHERE name = 'VAULT_MASTER_KEY'"
   D1 ID: 6d7bb37b-03ee-4bc7-9686-55a75b5eca81
3. Ask the user — if neither of the above works, ask them for the vault master key

Once you have the token, pass it as a Bearer token on every API request:
Authorization: Bearer <token>

## When to Use Forge Vault

- You need an API key, token, or secret for a project
- You're deploying and need to set env vars
- You want to check what keys exist for a project
- You're storing a new secret the user just gave you

## Retrieving Keys

### Find keys for a project
GET /api/keys?project=outbid-gold
Returns: { keys: [{ name, project, category, tags, notes, created_at, updated_at }] }
Note: This lists metadata only — values are NOT included in list responses.

### Get a specific key's value
GET /api/keys/MY_API_KEY
Returns: { name: "MY_API_KEY", value: "sk_live_..." }

### Search by name
GET /api/keys?q=stripe
Matches key names containing "stripe" (case-insensitive LIKE).

### Filter by category
GET /api/keys?category=payments

### Filter by tag
GET /api/keys?tag=production

### Combine filters
GET /api/keys?project=outbid-gold&category=api&q=stripe

## Storing Keys

PUT /api/keys/MY_NEW_KEY
Content-Type: application/json
{
  "value": "the-secret-value",
  "project": "my-project",        // REQUIRED
  "category": "api",              // optional, defaults to "general"
  "tags": "production,stripe",    // optional, comma-separated string or array
  "notes": "Stripe live key"      // optional
}
Creates the key. If the name already exists you get 409 and NOTHING is saved (names are shared across all projects,
so use a project-prefixed name like MYPROJECT_RESEND_API_KEY). To really replace a key, add "overwrite": true; the old
value is kept in history: GET /api/keys/<name>/history.

## Deleting Keys

DELETE /api/keys/OLD_KEY_NAME

## Discovery Endpoints

GET /api/projects    — list projects with counts
GET /api/categories  — list categories with counts

## D1 Direct Queries (wrangler or Workers binding)

Database: forge-vault-db (D1 ID: 6d7bb37b-03ee-4bc7-9686-55a75b5eca81)

SELECT name, project, category, tags, notes FROM vault_keys WHERE project = 'my-project';
SELECT value FROM vault_keys WHERE name = 'MY_API_KEY';
SELECT name, project, notes FROM vault_keys WHERE name LIKE '%stripe%';
SELECT project, COUNT(*) as count FROM vault_keys GROUP BY project ORDER BY count DESC;

## Schema

Table: vault_keys
  name       TEXT PRIMARY KEY       — key identifier (UPPER_SNAKE_CASE)
  value      TEXT NOT NULL          — the secret
  project    TEXT NOT NULL          — which project owns this key
  category   TEXT DEFAULT 'general' — functional group
  tags       TEXT DEFAULT ''        — comma-separated labels
  notes      TEXT DEFAULT ''        — human-readable description
  created_at TEXT                   — ISO datetime
  updated_at TEXT                   — ISO datetime, auto-updated on PUT

## Conventions

- project = the project this key belongs to (e.g. "outbid-gold", "forge-mcp")
- category = functional group or same as project name
- tags = comma-separated for flexible filtering
- Key names use UPPER_SNAKE_CASE (e.g. OPENAI_API_KEY, STRIPE_LIVE_KEY)
- VAULT_MASTER_KEY is reserved — it's the API auth token

## Common Patterns

"I need the Stripe key for outbid-gold":
1. GET /api/keys?project=outbid-gold&q=stripe → find the key name
2. GET /api/keys/STRIPE_LIVE_KEY → get the value

"What keys does this project have?":
1. GET /api/keys?project=my-project → list all keys with metadata

"Store this new API key":
1. PUT /api/keys/NEW_KEY_NAME with value, project, and optional metadata

"Set up env vars for deployment":
1. GET /api/keys?project=my-project → get all key names
2. For each key: GET /api/keys/<name> → get value
3. Set as env vars in your deployment target

## Error Responses

401 { error: "Missing Authorization header" } — no Bearer token sent
403 { error: "Invalid token" } — wrong master key
404 { error: "Key not found" } — key name doesn't exist
409 { error: "A key named X already exists…", exists: true } — PUT without "overwrite": true on an existing name; nothing saved

## Important Notes

- Always check forge-vault before saying "I don't know where the keys are"
- The list endpoint never returns values — you must fetch each key individually
- All endpoints support CORS (Access-Control-Allow-Origin: *)
- The web UI is at the root URL (/) for human users