Skip to content

API.md

Latest commit

 

History

History
183 lines (142 loc) · 3.92 KB

API.md

File metadata and controls

183 lines (142 loc) · 3.92 KB
Raw

REST API Reference

The API runs on port 3001 by default and is consumed by the Roblox Lua loader for real-time key validation.

Health & Status

GET /

Server information and feature list.

Response 200:

{
  "status": "ok",
  "server": "FYY PREMIUM VALIDATION API",
  "version": "4.0.0",
  "database": "MongoDB",
  "features": ["username_lock", "hwid_blacklist", "trial_support", "auto_bind"],
  "time": "2026-02-15T03:45:12.000Z"
}

GET /ping

Health check with database connectivity status.

Response 200:

{
  "status": "ok",
  "message": "pong",
  "database": "connected",
  "timestamp": "2026-02-15T03:45:12.000Z"
}

Key Validation

GET /check

Primary validation endpoint called by the Lua loader on every script execution.

Parameter Type Required Description
key string Yes License key (FYY-... or TRIAL-...)
hwid string Yes Client hardware ID
robloxId string Yes Roblox user ID
placeId string Yes Roblox place/game ID
username string Yes Roblox display username

Success response:

{
  "status": "ok",
  "code": "OK",
  "usernames": ["Player1", "Player2"],
  "maxUsernames": 2,
  "availableSlots": 0,
  "action": "already_registered"
}

Response codes:

Code Meaning
OK Key valid, username registered
FIRST_BIND Key valid, HWID bound for the first time
AUTO_BIND Username auto-bound to an available slot
INVALID_KEY Key does not exist
BLACKLISTED Key is blacklisted
EXPIRED Key has expired
HWID_MISMATCH Wrong device for this key
HWID_BLACKLISTED Device is globally blacklisted
USERNAME_NOT_FOUND Username not registered and no slots available
MISSING_PARAMS Required query parameters missing

GET /key-info

Retrieve key details for status lookups.

Parameter Type Required Description
key string Yes License key

Success response:

{
  "status": "ok",
  "key": "FYY-ABCDE-12345-FGHIJ",
  "usernames": ["Player1"],
  "maxUsernames": 2,
  "availableSlots": 1,
  "expiresAt": "2027-01-01T00:00:00.000Z",
  "isTrial": false,
  "blacklisted": false
}

Admin Endpoints

All admin endpoints require the X-API-Key header. Requests without it get 401 Unauthorized.

GET /stats

Returns system-wide statistics.

Response 200:

{
  "status": "ok",
  "totalKeys": 500,
  "normalKeys": 450,
  "activeNormalKeys": 420,
  "trialKeys": 50,
  "activeTrials": 30,
  "blacklistedKeys": 10,
  "hwidBlacklistCount": 5,
  "totalUsernames": 380,
  "keysWithUsernames": 200,
  "database": "MongoDB",
  "uptime": 86400,
  "memory": { "rss": 52428800, "heapUsed": 30000000 }
}

GET /check-hwid

Check if a specific HWID is blacklisted.

Parameter Type Required Description
hwid string Yes Hardware ID to check

Response 200:

{
  "status": "ok",
  "hwid": "ABC123...",
  "blacklisted": true,
  "reason": "Reverse engineering attempt",
  "blacklistedAt": "2026-01-15T10:30:00.000Z"
}

Error Responses

All errors share the same JSON shape:

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Human-readable error message"
}
HTTP Code Cause
400 MISSING_PARAMS Required query string missing
401 UNAUTHORIZED Missing or invalid X-API-Key
404 INVALID_KEY Key not found in database
500 INTERNAL_ERROR Unexpected server error

Rate Limits

No rate limits currently. Recommended client behavior:

  • Cache successful /check response for 30 minutes
  • On HWID_MISMATCH / BLACKLISTED, stop retries and show error
  • On INTERNAL_ERROR, exponential backoff

See also: ARCHITECTURE.md, SECURITY.md