# How to Enable and Configure the Admin Dashboard in Grok2API

> Learn how to enable and configure the admin dashboard in Grok2API. Secure routes, authenticate, and access dashboard data with our easy-to-follow guide.

- Repository: [Chenyme/grok2api](https://github.com/chenyme/grok2api)
- Tags: how-to-guide
- Published: 2026-07-16

---

**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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/startup.go)). This creates the admin user and secures all admin routes.

2. **Expose Admin Routes**: The HTTP server ([`server.go`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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:

```bash
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:

```bash
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:

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

```

Using the Go SDK:

```go
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`](https://github.com/chenyme/grok2api/blob/main/backend/internal/app/startup.go): Boots the admin auth service and injects dependencies.
- [`backend/internal/transport/http/server.go`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/backend/internal/transport/http/adminauth/handler.go): Implements login, token refresh, and session management.
- [`backend/internal/transport/http/dashboard/handler.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/transport/http/dashboard/handler.go): Parses query parameters and returns JSON responses.
- [`backend/internal/application/dashboard/service.go`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/backend/internal/application/dashboard/service.go).