> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nullpass.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Statistics

> Get user statistics (admin only)

## Endpoint

```
GET /api/admin/users/stats
```

## Overview

Retrieves aggregate user statistics including total users, premium users, and free users. Requires admin access via DROP service `accessFlags` or `INTERNAL_SECRET`.

## Request

Requires authentication via Bearer token (with admin privileges) or `x-internal-secret` header.

## Response

<ResponseField name="totalUsers" type="number">
  Total number of users in the system
</ResponseField>

<ResponseField name="premiumUsers" type="number">
  Number of users with premium DROP service access
</ResponseField>

<ResponseField name="freeUsers" type="number">
  Number of users without premium DROP service access (totalUsers - premiumUsers)
</ResponseField>

## Authentication

### Admin Access via DROP Service

User must have DROP service entitlement with:

* `accessFlags.isNullDropTeam`: `true`
* `accessFlags.nullDropTeamRole`: `"founder"` or `"dev"`

### Internal Secret

Alternatively, use `x-internal-secret` header with `INTERNAL_SECRET` value.

## Implementation Details

### Code Reference

```8:57:nullpass_clean/src/app/api/admin/users/stats/route.ts theme={null}
export async function GET(request: NextRequest) {
  const corsResponse = handleCors(request)
  if (corsResponse) return corsResponse

  const internalSecret = request.headers.get('x-internal-secret')
  const isInternal = INTERNAL_SECRET && internalSecret === INTERNAL_SECRET

  if (!isInternal) {
    const auth = await requireAuth(request)
    if ('error' in auth) {
      return auth.error
    }

    const dropService = await prisma.userServiceEntitlement.findUnique({
      where: {
        userId_service: {
          userId: auth.userId,
          service: 'DROP',
        },
      },
    })

    const accessFlags = (dropService?.accessFlags as any) || {}
    const isAdmin = accessFlags.isNullDropTeam && ['founder', 'dev'].includes(accessFlags.nullDropTeamRole)

    if (!isAdmin) {
      return errorResponse('Forbidden - Admin access required', 403, request.headers.get('origin'))
    }
  }

  try {
    const totalUsers = await prisma.user.count()
    
    const premiumUsers = await prisma.userServiceEntitlement.count({
      where: {
        service: 'DROP',
        isPremium: true,
      },
    })

    return jsonResponse({
      totalUsers,
      premiumUsers,
      freeUsers: totalUsers - premiumUsers,
    }, 200, request.headers.get('origin'))
  } catch (error) {
    console.error('Admin users stats error:', error)
    return errorResponse('Internal server error', 500, request.headers.get('origin'))
  }
}
```

## Status Codes

<ResponseField name="200" type="OK">
  Success
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Missing or invalid authentication
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Admin access required
</ResponseField>

## Example Request

```bash theme={null}
curl -X GET https://auth.nullpass.xyz/api/admin/users/stats \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Example Response

```json theme={null}
{
  "totalUsers": 1000,
  "premiumUsers": 250,
  "freeUsers": 750
}
```

## Notes

* Premium users are counted based on DROP service `isPremium` flag
* Free users calculation: `totalUsers - premiumUsers`
* Statistics are real-time (not cached)


## OpenAPI

````yaml GET /admin/users/stats
openapi: 3.1.0
info:
  title: Null Pass API
  description: >-
    Internal API documentation for Null Pass authentication and service
    management system
  version: 1.0.0
servers:
  - url: https://auth.nullpass.xyz/api
security: []
paths:
  /admin/users/stats:
    get:
      tags:
        - Admin
      summary: Get User Statistics
      description: Get aggregate user statistics (admin only)
      responses:
        '200':
          description: User statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStats'
      security:
        - bearerAuth: []
components:
  schemas:
    UserStats:
      type: object
      properties:
        totalUsers:
          type: integer
        premiumUsers:
          type: integer
        freeUsers:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````