Skip to main content

Overview

The theAuth dashboard is a visual interface for everything the SDK manages through code: creating and revoking agents, reviewing audit logs, inspecting delegation chains, and monitoring permissions. It is optional. You can use the SDK entirely through code without the dashboard. It ships in two forms:
  1. A React component (@glinr/theauth-dashboard) you embed in an existing app
  2. A standalone CLI server you run without any frontend code

Quick start (demo mode)

The fastest way to see the dashboard in action:
This starts a full theAuth instance with in-memory SQLite, seeds sample data (3 agents, permissions, audit entries, a delegation chain), and serves the dashboard on http://localhost:3100 (set another port with --port). To add a login screen:
When THEAUTH_DASHBOARD_SECRET is set, the dashboard shows a password prompt before granting access. Without it, the server prints a warning and the dashboard login accepts anyone (suitable for local development only).
Demo mode uses an in-memory database. All data is lost when the server stops. For persistent data, embed the dashboard in your app and point it at a real database.

Installation

Install the package:
Render TheAuthDashboard inside a protected route in your app. (AuthDashboard is a deprecated alias for the same component.)

Component props

string
required
Base URL of the API. The dashboard calls ${apiUrl}/api/... (for example /api/agents, /api/audit, /api/dashboard/stats), see the endpoint list below.
'light' | 'dark'
Initial color scheme. Defaults to 'dark'. A choice made with the header toggle is saved in localStorage and takes precedence on later visits. There is no 'system' option.
boolean
When true, shows a banner indicating sample data.
The component peer-depends on React 19 or later.

Backend

The dashboard needs an HTTP backend that serves the paths listed under “API endpoints” below, all under an /api prefix on apiUrl. The framework adapters (theAuthNextjs, theAuthHono, theAuthExpress, and the others) serve the agent, authorization, delegation, audit, and dashboard/* routes of the core API (mounted under /api/theauth by default), but they do not serve every route the dashboard calls: /users, /permissions/templates, /settings, /mcp/servers (list), and /agents/:id/permissions are only implemented in the CLI’s demo server. The dashboard also revokes agents with POST /agents/:id/revoke, while the Hono adapter exposes revocation as DELETE /agents/:id, so that route needs a small shim of your own. The adapter paths also have no /api prefix of their own, so mount the adapter so that its routes resolve under /api on the host you pass as apiUrl. Treat the embedded component as something you wire to your own /api routes, and use the standalone CLI if you only want to look at the UI.

Login gate

The component always renders its own login gate. On load it checks a secret stored in sessionStorage against GET ${apiUrl}/api/dashboard/auth (with an Authorization: Bearer <secret> header), and shows a password screen when that check fails. Your backend must implement /api/dashboard/auth (return 200 when the bearer secret is valid) or the dashboard never gets past the login screen. The core adapters do not implement it. The CLI servers implement it with THEAUTH_DASHBOARD_SECRET.

Route protection

That secret gate is not a replacement for your app’s own access control. Wrap the page with your own auth check as well:
Do not render the dashboard on a public route. It gives full read/write access to all agents, permissions, and audit data.

Dashboard pages

The dashboard has nine pages accessible from the sidebar. Overview: Active agent count, authorization rate (allowed vs denied), recent audit entries with live refresh, and quick action buttons. Agents: List all agents with status badges. Create new agents with initial permissions, rotate tokens, and revoke agents. Click an agent to see its permissions, recent audit entries, and delegation chains. Users: List human users who own agents, with agent counts. Permissions: Create and manage permission templates. Templates let you define a permission set once and apply it to multiple agents. Supports visual and raw JSON editing modes. Delegations: View all active delegation chains. Shows the from/to agents, delegated permissions, depth, and expiry countdown. Devices: Fleet counters, the device list with suspend, resume and revoke, and the enrollment token list with usage (uses / maxUses) and state. The secret of a token is shown once when you create it and is never listed again. Open a device to edit its groups, add a pre shared key, public JWK or certificate thumbprint, revoke a credential, or issue a signed policy bundle. A generated key is shown once. See IoT devices. MCP Servers: Register MCP servers with their endpoints, tools, and auth requirements. Monitor status and token validation activity. Audit Log: Full queryable log of every authorization decision. Filter by agent, action, result, decision code, and date range. Each row shows its decision code, and the Why button opens a drawer that explains the decision through POST /explain. Export as JSON or CSV for compliance. See Observability. Security: Security-focused view showing rate-limited agents, recent denials, revoked agents, and expired tokens. Settings: Database connection info, token expiry policy, rate limit defaults, and audit retention settings.

Light and dark mode

The dashboard supports both light and dark themes. A toggle button in the top-right header switches between them. The preference is saved to localStorage and persists across sessions. When embedded as a React component, pass theme="light", theme="dark", or theme="system" to set the initial mode.

API endpoints

The dashboard calls these REST endpoints on ${apiUrl}, each under an /api prefix (for example /api/agents). If you are building a custom dashboard or integrating with other tools, here is the list the client uses. Paths are shown without the prefix: The core handler serves the agents, audit, delegations, approvals, revocations, devices, explain and /dashboard/stats routes. It does not serve /users, /permissions/templates, /settings or /mcp/servers, and /dashboard/auth is yours to add (see the login gate above). Only the CLI demo server (theauth dev) answers the four routes marked above. Against a server without them, the Users, Permissions, Settings and MCP Servers pages show a “does not serve” message instead of data.

Agent identity

Create, rotate, and revoke agents from code instead of the dashboard.

Audit trail

Query and export the same audit data the dashboard surfaces.

UI components

React components for sign-in forms and session management.

Terraform

Manage agents and permissions as code for reproducible environments.
Last modified on October 19, 2026