Overview

The admin API lets you manage lexicons, monitor records, run backfill jobs, and control user access. All endpoints live under /admin and require authentication from a DID that exists in the happyview_users table, with the appropriate permissions for the endpoint being called. You can also manage all of this through the web dashboard.

Auth

The admin API supports three authentication methods:

1. API keys — read/write tokens starting with hv_, passed as Authorization: Bearer hv_.... See the API Keys guide for details.
2. Service auth JWT — atproto inter-service authentication via signed JWTs.
3. Cookie-based session auth — signed session cookies set during the dashboard OAuth login flow. The web dashboard uses this method.

In all cases the resolved DID is checked against the happyview_users table, and the user's permissions are loaded to authorize the request.

Auto-bootstrap: If the happyview_users table is empty, the first authenticated request automatically creates the caller as the super user with all permissions granted.

Non-user DIDs receive a 403 Forbidden response. Users without the required permission for a specific endpoint also receive 403 Forbidden.

Errors

All error responses return JSON with an error field:

{
  "error": "description of what went wrong"
}

# All examples assume $TOKEN is an API key (hv_...)
AUTH="Authorization: Bearer $TOKEN"

Endpoint groups

Permissions

Each admin API endpoint requires a specific permission. See the Permissions guide for the full list of permissions and templates.