Administrator Guide Overview

This section covers how to configure, manage, and monitor a TokenHub deployment.

Administration Model

TokenHub uses a three-tier security model:

  1. Admin token (TOKENHUB_ADMIN_TOKEN): Authenticates access to the admin API (/admin/v1/*) and the admin dashboard. The UI requires the token at login; all admin API calls include it as Authorization: Bearer <token>. Retrieve it with tokenhubctl admin-token.
  2. Vault password: A separate secret that encrypts provider API keys at rest. Even a valid admin token cannot decrypt the vault — the vault must be explicitly unlocked after each restart (or set TOKENHUB_VAULT_PASSWORD for auto-unlock).
  3. API keys: Issued to client applications for /v1 endpoint access. Managed via the admin API or UI.

In production, always set TOKENHUB_ADMIN_TOKEN and restrict network access to /admin/* at the firewall, VPN, or reverse proxy level.

Administration Tools

Admin UI

The built-in web dashboard at /admin provides a graphical interface for all admin operations. See Admin UI.

tokenhubctl

A command-line tool for scripting and quick administration. Covers all admin API operations. See tokenhubctl CLI.

curl / Admin API

All operations are available via the REST API at /admin/v1/*. See API Reference.

Admin Endpoints

CategoryEndpointsPurpose
Vault/admin/v1/vault/*Lock, unlock, rotate vault password
Providers/admin/v1/providersRegister, edit, and manage LLM providers
Models/admin/v1/modelsRegister, edit, and manage model configurations
Discovery/admin/v1/providers/{id}/discoverDiscover models from a provider's API
Simulation/admin/v1/routing/simulateWhat-if routing simulation
Routing/admin/v1/routing-configSet default routing policy
API Keys/admin/v1/apikeysCreate, rotate, revoke client API keys
Health/admin/v1/healthView provider health status
Stats/admin/v1/statsView aggregated request statistics
Logs/admin/v1/logsView request logs
Audit/admin/v1/auditView audit trail
Rewards/admin/v1/rewardsView contextual bandit reward data
Engine/admin/v1/engine/modelsView runtime model registry and adapter info
TSDB/admin/v1/tsdb/*Query time-series metrics
Workflows/admin/v1/workflowsView Temporal workflow executions
Events/admin/v1/eventsSSE stream of real-time events

Sections