Docs

Connect in 5 minutes

Three steps and one check command. The full documentation is currently in German at tokenwacht.de/doku; the code samples are language-neutral.

Step 1 · Create a Tokenwarden key

Register for free, open Anbindung (Connection) in the cockpit, create a key. Scope it to proxy, ingest or read, or leave it unrestricted. Store it as TOKENWACHT_KEY.

Step 2 · Swap the base URL

from anthropic import Anthropic
client = Anthropic(base_url="https://tokenwacht.de/anthropic", api_key=os.environ["ANTHROPIC_API_KEY"],
                   default_headers={"X-TW-Key": os.environ["TOKENWACHT_KEY"], "X-TW-Agent": "nils-icp-research"})

from openai import OpenAI
client = OpenAI(base_url="https://tokenwacht.de/openai/v1", default_headers={"X-TW-Key": …, "X-TW-Agent": "…"})

# Gemini: base URL https://tokenwacht.de/gemini (keep x-goog-api-key)
# Bedrock: https://tokenwacht.de/bedrock/model/<id>/converse with a Bedrock API key as Bearer
# Azure OpenAI: azure_endpoint="https://tokenwacht.de/azure" plus header X-TW-Ziel: https://<resource>.openai.azure.com
# Mistral, DeepSeek, Groq, OpenRouter: OpenAI client with base URL https://tokenwacht.de/<provider>/v1
# Own servers (Ollama, vLLM, LiteLLM): create a custom target in the cockpit, then https://tokenwacht.de/ziel/<name>/v1

Header	Required	Meaning
`X-TW-Key`	yes	Your Tokenwarden key. Nothing is forwarded without it.
`X-TW-Agent`	recommended	The agent as a durable unit.
`X-TW-Run`	recommended	Run id (UUID or text). If missing, runs are formed automatically (15 minutes of silence = new run).
`X-TW-Step`, `X-TW-Kunde`, `X-TW-Funktion`, `X-TW-Benutzer`	optional	Step, end customer (re-billing), function, user.

Step 3 · Verify

curl https://tokenwacht.de/v1/anbindung/pruefen -H "Authorization: Bearer $TOKENWACHT_KEY"

ok: true plus a letztes_ereignis (last event) matching your call means you are connected. The cockpit page Anbindung shows the first call live.

Rejection (HTTP 402)

{"fehler": "tokenwacht_budget_ueberschritten", "regel": "lauf_budget", "grenze": "2.5000", "verbraucht_eur": "2.5400",
 "schritte": 41, "lauf_id": "…", "hinweis": "…", "cockpit_url": "…"}

Other paths

Python SDK (sdk/python): run context, headers, BudgetUeberschritten.
Node SDK (sdk/node): fetch replacement for Anthropic/OpenAI clients, run context via AsyncLocalStorage.
n8n: HTTP Request node with the headers above, or the community package n8n-nodes-tokenwacht.
Claude Code: Stop hook sdk/claude-code-hook reports every session as a run, no content.
Chrome extension: counts claude.ai, ChatGPT and Gemini on the network level, estimated tokens, never content.
Ingest: POST /v1/ereignisse with your own usage numbers, batches of up to 500, idempotent.
API: GET /v1/api/verbrauch?gruppe=agent|endkunde|modell|tag, OpenAPI at /docs.

Enterprise and self-hosting

SSO via OpenID Connect, audit log, scoped API keys, data export, deletion after 30 days. Self-hosting with Docker Compose or Kubernetes and a licence key. Details (German): Team and security, Self-hosting, Troubleshooting.