Security & Best Practices

The agent platform's auth model is straightforward: every non-public action requires a token issued by Elven. Most failure modes come from how those tokens are handled on the client side. This page covers the practices that matter.

Token types

Type	Lifetime	How to obtain	When to use
JWT session	~1 hour, auto-refreshed via `sync.elvenvtt.com/v1/auth/refresh`	`elven login` (browser OAuth)	Interactive use from your own machine
Personal access token (PAT) `el_pat_*`	Long-lived, no auto-expiry unless you set `expiresInDays`	Studio Developer → CLI Tokens, or `elven tokens create`	CI, headless environments, MCP agents, cloud-hosted Claude

PATs are stored server-side as SHA-256 hashes only. The plaintext is shown once on creation and never again.

Bring Your Own Anthropic Key (BYOK)

If you add an Anthropic API key in Settings → AI, Elven calls Anthropic directly with your key for the AI Agent and AI Lab — Anthropic bills your account, our daily/monthly cost caps don't apply, and you don't need a Creator subscription for those features.

How it's handled:

Validated before storage. We make a one-token test call to Anthropic with the key. If Anthropic rejects it, we don't store anything.
Encrypted at rest. AES-GCM-256, with the master key held only as a Cloudflare Worker secret (BYOK_ENCRYPTION_KEY). Stored in Postgres user_ai_configs, RLS-restricted to the owning user.
Plaintext never logged. The only thing we keep in the clear is the last 4 characters, for UI display ("ending in …X1Y2").
Used only for your AI calls. Loaded just-in-time per request, decrypted in worker memory, never persisted in logs, KV, or analytics.

What a leaked Anthropic key would mean

If your Anthropic key were to leak (more likely from your own machine than from us, given the encryption above), an attacker could rack up Anthropic charges on your account. Mitigations:

Remove the key from Elven at Settings → AI → Remove. The AI agent falls back to managed inference (requires Creator) until you add a new key.
Rotate the key at Anthropic at console.anthropic.com/settings/keys — revoke the old one, mint a new one.
Paste the new key back into Settings → AI.

You should rotate periodically even without a known leak, the same as any long-lived API credential.

What a leaked token can do

If someone gets your PAT, they can act as you for any operation the agent platform exposes: create/edit/delete listings, posts, drops; publish files to your CDN prefix; mint more PATs (up to the 10-per-user limit); see your sales and analytics; start Stripe Connect onboarding flows.

What they can't do:

Redirect your existing Stripe payouts. Stripe's own KYC blocks that.
Read your password or change your email.
Mint a JWT session (those come from Supabase password / OAuth flows, not from a PAT).

Best practices

Don't commit tokens to source control

The most likely leak is a .mcp.json or shell script with a token inline pushed to a public GitHub repo. Two ways to keep them out:

Use environment variables. All transports (elven login --token, elven-mcp-account, the HTTP MCP) accept ELVEN_TOKEN as an env var instead of a config file.
```
// .mcp.json — token reference, not the literal value
{
  "mcpServers": {
    "elven-account": {
      "command": "elven-mcp-account",
      "env": { "ELVEN_TOKEN": "${ELVEN_TOKEN}" }
    }
  }
}
```
Set ELVEN_TOKEN in your shell config (.bashrc, .zshrc) or your IDE's env settings, never in the file.
Add to .gitignore. Treat .mcp.json like .env. If you must commit a template, use placeholders.
```
# .gitignore
.mcp.json
.env
```

Use short-lived tokens for ephemeral environments

For CI runners that finish in minutes, set --expires-in-days 1 (or even less via the worker API). Once the job finishes, the token's window of usefulness is bounded:

elven tokens create --label "ci-publish-prod" --expires-in-days 1

Audit and revoke

Every PAT now tracks last-used-at and last-used IP (since 0.7.2). Surface in Studio Developer → CLI Tokens:

"Last used 14d ago from 75.x.y.z" — looks like a CI runner I set up, fine.
"Last used 2h ago from a different country" — that's a problem; revoke immediately.
"Never used" — created and forgotten; consider revoking.

Revoking is instant. The server's KV index drops the token's hash; subsequent requests with that token return 401.

Separate tokens per use case

One PAT per integration. If your laptop, GitHub Actions, and a hosted Claude config all share one token, revoking it nukes all three. Per-integration tokens let you cycle one without disrupting the others.

elven tokens create --label "laptop"
elven tokens create --label "github-actions-publish"
elven tokens create --label "claude-web-mcp"

What the platform does to protect you

Rate limiting on mcp.elvenvtt.com/mcp. 60 requests per minute per token. An agent stuck in a loop hits 429 instead of running up your CF Worker bill or our backend cost.
Last-used tracking. As above. KV write is throttled to ~1/min/token so it doesn't blow up storage costs.
Per-user PAT cap (10). A compromised account can't mint a million tokens.
Server-side hashing. Token plaintext is never persisted anywhere we control.
CF-Connecting-IP captured per request. Spoof-resistant; lets you see where your token has been used.
Auto-revocation on Stripe onboarding hijack attempts. Stripe's KYC ensures payouts can't be redirected to a third party even if a token is compromised.

What we don't do (yet)

These are real gaps to be aware of:

No GitHub secret-scanning partnership yet (submission in flight). Once accepted, GitHub will detect el_pat_* tokens in public commits and auto-revoke server-side.
No per-user upload quota. A compromised token could fill your CDN prefix with junk files (each capped at 25MB, but no total cap). Mitigation: revoke + we manually clean up.
No rate limits on writes outside MCP. listing.create, post.new, etc. don't currently have per-token throttling. Planned.
No "this token is being used from an unfamiliar IP" alerts. You have to look at the Studio tab manually.

Reporting a suspected compromise

If you think a token has leaked or you see unexpected activity:

Revoke the token immediately from Studio Developer → CLI Tokens. Takes effect within a second.
Check your listings — elven listing mine --json — for anything you didn't create.
Check your published files — https://api.elvenvtt.com/packs/c/{your-slug}/ — for content that shouldn't be there.
Email security@elvenvtt.com with the token id and approximate compromise window if you want help auditing.

Don't post a leaked token publicly when reporting (don't put it in a GitHub issue). Email is the right channel.

Token types​

Bring Your Own Anthropic Key (BYOK)​

What a leaked Anthropic key would mean​

What a leaked token can do​

Best practices​

Don't commit tokens to source control​

Use short-lived tokens for ephemeral environments​

Audit and revoke​

Separate tokens per use case​

What the platform does to protect you​

What we don't do (yet)​

Reporting a suspected compromise​