How to Enable and Configure the Admin Dashboard in Grok2API

To enable the admin dashboard in Grok2API, start the admin authentication service to secure the /api/admin/v1 routes, authenticate via POST /api/admin/v1/auth/login to obtain a refresh token, then query GET /api/admin/v1/dashboard with optional period, timezone, and refresh parameters.

The admin dashboard in Grok2API provides real-time analytics and usage metrics for your API deployment. According to the chenyme/grok2api source code, the dashboard is served through a protected admin API and requires specific initialization steps to enable and configure properly. This guide walks through the exact implementation details found in the repository.

Architecture and Prerequisites

Admin Authentication Service

Before accessing the dashboard, the admin authentication service must be initialized. In backend/internal/app/startup.go, the service creates the admin user and sets up the security layer. This service is then injected into backend/internal/transport/http/server.go as AdminAuth middleware that protects all admin routes.

Route Registration

The dashboard handler is mounted under the /api/admin/v1 route group. In server.go, the router creates a protected group using router.Group("/api/admin/v1") and registers the dashboard handler with dashboardhttp.NewHandler(deps.Dashboard).Register(adminProtected). This automatically exposes GET /api/admin/v1/dashboard and applies the authentication middleware.

Step-by-Step Enabling Process

1. Start the Admin Service: Ensure the admin authentication service is instantiated during application startup (startup.go). This creates the admin user and secures all admin routes.

2. Expose Admin Routes: The HTTP server (server.go) must register the admin route group and apply the AdminAuth middleware to protect the endpoints.

3. Authenticate: Send a POST request to /api/admin/v1/auth/login (implemented in backend/internal/transport/http/adminauth/handler.go) with valid credentials. The response includes an access token and a refresh token stored in an HttpOnly cookie named grok2api_admin_refresh.

4. Query the Dashboard: With the authentication cookie, send a GET request to /api/admin/v1/dashboard. The handler in backend/internal/transport/http/dashboard/handler.go forwards your query parameters to the dashboard service.

5. Force Data Refresh: Append ?refresh=1 to bypass the 15-second cache and retrieve the latest data snapshot.

Configuring Dashboard Parameters

The dashboard supports three query parameters to customize the analytics view:

• period: Time range for aggregation. Supported values are 24h, 7d, 30d, or 90d. Defaults to 24h.
• timezone: IANA timezone identifier (e.g., America/New_York, Asia/Shanghai). Defaults to UTC.
• refresh: Set to 1 to skip the cache and force a fresh data load. Defaults to 0.

The aggregation logic and validation are handled in backend/internal/application/dashboard/service.go, which returns specific errors (ErrInvalidPeriod, ErrInvalidTimezone) for invalid inputs.

Authentication and Security

The dashboard uses cookie-based session management. After logging in via the admin authentication handler, the grok2api_admin_refresh HttpOnly cookie is automatically sent with subsequent requests. The AdminAuth middleware validates this token before allowing access to the dashboard endpoint. This security model is implemented in the transport layer of the chenyme/grok2api repository.

Practical Code Examples

Authenticate and save the session cookie:

curl -X POST https://your-host/api/admin/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}' \
  -c cookies.txt

Request dashboard data for a specific period and timezone:

curl -X GET "https://your-host/api/admin/v1/dashboard?period=7d&timezone=Asia/Shanghai" \
  -b cookies.txt

Force a fresh data load bypassing the cache:

curl -X GET "https://your-host/api/admin/v1/dashboard?period=30d&refresh=1" \
  -b cookies.txt

Using the Go SDK:

client := grok2api.NewClient("https://your-host")
if err := client.AdminAuth.Login(context.Background(), "admin", "your-password"); err != nil {
    log.Fatalf("login failed: %v", err)
}
dash, err := client.Dashboard.Get(context.Background(),
    grok2api.DashboardQuery{Period: "7d", Timezone: "Europe/Berlin"})
if err != nil {
    log.Fatalf("dashboard error: %v", err)
}
fmt.Printf("Requests in last 7 days: %d\n", dash.Usage.Requests)

Key Implementation Files

Understanding these source files helps with advanced configuration:

• backend/internal/app/startup.go: Boots the admin auth service and injects dependencies.
• backend/internal/transport/http/server.go: Registers the /api/admin/v1 route group and applies the AdminAuth middleware.
• backend/internal/transport/http/adminauth/handler.go: Implements login, token refresh, and session management.
• backend/internal/transport/http/dashboard/handler.go: Parses query parameters and returns JSON responses.
• backend/internal/application/dashboard/service.go: Contains aggregation logic, period parsing, timezone validation, and caching logic.

Summary

• The Grok2API admin dashboard is served at /api/admin/v1/dashboard and requires the admin authentication service to be running.
• Authentication uses HttpOnly cookies (grok2api_admin_refresh) obtained from the /api/admin/v1/auth/login endpoint.
• Query parameters include period (24h, 7d, 30d, 90d), timezone (IANA format), and refresh (to bypass the 15-second cache).
• The implementation spans the startup configuration, HTTP transport layer, and application service layer in the chenyme/grok2api codebase.

Frequently Asked Questions

How do I access the Grok2API admin dashboard?

First, ensure the admin authentication service is initialized in backend/internal/app/startup.go. Then POST your credentials to /api/admin/v1/auth/login to receive a session cookie, and finally GET /api/admin/v1/dashboard with that cookie to view the analytics.

What authentication method does the admin dashboard use?

The dashboard uses cookie-based session authentication. The login endpoint sets an HttpOnly cookie named grok2api_admin_refresh containing the refresh token, which the AdminAuth middleware validates on every dashboard request according to the source code in backend/internal/transport/http/server.go.

How long is the dashboard data cached?

Dashboard data is cached for 15 seconds by default. To bypass this cache and retrieve real-time data, append ?refresh=1 to your dashboard request URL, which skips the short-term cache implemented in the dashboard service layer.

Can I use a custom timezone for dashboard analytics?

Yes, pass any valid IANA timezone identifier (such as America/New_York or Asia/Shanghai) via the timezone query parameter. If omitted, the dashboard defaults to UTC. Invalid timezone strings return an ErrInvalidTimezone error from the service layer in backend/internal/application/dashboard/service.go.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}