Users

Admin endpoints to search for accounts and inspect user metadata.

Auth

All routes require a valid API JWT with admin:user:view.

Lookup users

GET /v1/admin/users/lookup?query={name-or-uuid}&limit=10

Searches by username prefix (case-insensitive) or a UUID. limit is optional and capped at 50.

Response:

{
  "items": [
    {
      "userId": "c959d9f9-dcbd-4054-8c4c-d5c305997bc0",
      "name": "Somebody",
      "homeRegion": "eu-central",
      "lastSeenAt": "2026-01-22T08:40:00Z"
    }
  ]
}

Get user detail

GET /v1/admin/users/{userId}

Response:

{
  "userId": "c959d9f9-dcbd-4054-8c4c-d5c305997bc0",
  "name": "Somebody",
  "homeRegion": "eu-central",
  "lastRegion": "eu-central",
  "createdAt": "2026-01-05T12:00:00Z",
  "updatedAt": "2026-01-20T12:00:00Z",
  "firstJoinedAt": "2026-01-05T12:00:00Z",
  "lastSeenAt": "2026-01-22T08:40:00Z",
  "lastRegionAt": "2026-01-22T08:40:00Z",
  "allowFriendRequests": true
}

Authenticated saved-server reads

Authenticated social clients can read another user's saved public-server list through:

• GET /v1/users/{id}/public-servers/saved
• GET /v1/users/{id}/public-servers/favorites

Access is allowed when one of these conditions is true:

• the caller is reading their own user id,
• the caller has social:servers.read.others,
• the caller has admin:user:view,
• the target user's privacy.serverListVisibility allows it (PUBLIC for any authenticated user, FRIENDS for confirmed friends, PRIVATE for nobody else).

Response shape:

{
  "items": [
    {
      "id": "680188af2d0e5b1594f42331",
      "address": "play.example.net:25565",
      "displayName": "Example Server",
      "saved": true,
      "savedPosition": 0,
      "favorite": true,
      "favoriteCount": 42
    }
  ],
  "serverIds": ["680188af2d0e5b1594f42331"],
  "counts": {
    "total": 1,
    "favorites": 1
  }
}

GET /v1/users/{id}/public-servers/favorites returns the same payload shape, filtered to entries with favorite=true.