API hardening — migration guide
Breaking changes for existing integrations (auth, server secret, webhooks, routes)
GuÃa de migración — seguridad API (Game Panel)
Audiencia: integradores (cliente, servidor dedicado, herramientas).
Base URL:
https://gamepanel.idcgames.com/api/v1 Actualizado: octubre 2026.
---
Modelo de confianza (importante)
1. Jugador (cliente de juego)
- 1. Login (
auth/third-party/logino legacy) congame_public_token(prefijogpp_…, en Edit Game → Public token). Puede ir en el cliente o en un microservicio de login. - 2. El panel devuelve un session token (
Authorization: Bearer …). - 3. Todas las APIs de jugador usan únicamente ese Bearer.
game_id+game_secret_token(alias API del valor almacenado comogamepanel_secret_tokenen BD)- Body o headers
X-Game-Secret/X-Gamepanel-Secret - Sin Bearer de jugador (salvo batch stats, que lleva tokens de sesión por jugador en el payload)
- Embeber
game_secret_token/ server secret en el .exe / APK (usa sologame_public_tokenpara login). - Enviar el secret en cada
POST user/stats/submitoprogression/process-matchcon Bearer (ya no se exige ni se debe usar).
Compatibilidad: en login se acepta también el alias temporal
game_public_secret (mismo valor que game_public_token). El server secret no vale en login. En rutas S2S solo game_secret_token / gamepanel_secret_token, nunca el público.Tres credenciales (por qué existen)
| Credencial | Dónde vive | Para qué | ¿En el cliente del juego? |
|---|---|---|---|
game_public_token (gpp_…) | Edit Game → Public token | Demostrar en login que la app pertenece al juego (auth/third-party/login, legacy auth/login). Sustituye meter el secret en el APK. | Sà (o en tu backend de login, nunca el secret) |
| Session Bearer | Respuesta de login | Identidad del jugador en todas las APIs auth.api (inventario, amigos, announcements/user, etc.). | Sà (token de sesión, no el secret) |
game_secret_token / gamepanel_secret_token | Edit Game → Server secret | Solo server-to-server: batch stats, compras externas, webhooks, /server/*. Nivel GameCredentialLevel::SERVER. | Nunca |
Los anuncios: antes del login usa
GET announcements/game?game_id=… (público). Con sesión, GET announcements/user usa solo el Bearer; el panel ya sabe qué GameUser eres y filtra con matchesUser() — no hace falta ningún token de juego en esa llamada.Rutas sin Bearer de jugador (servidor / login / catálogo público)
| Tipo | Ejemplos | Auth |
|---|---|---|
| Login | POST auth/third-party/login | game_public_token + plataforma |
| Refresh | POST auth/refresh | refresh_token |
| Stats S2S | POST user/stats/submit-batch | game_secret_token + players[].token |
| MMR lookup | POST user/mmr/lookup | game_secret_token |
| Tienda externa | POST purchases/external, webhooks IDC | game_secret_token o HMAC |
| Bootstrap | POST server/progression/initialize | game_secret_token |
| Market browse | GET /api/v1/market/offers?game_id=… (legacy /api/market/…) | Público; game_id obligatorio; throttle por IP (GAME_API_PUBLIC_READ_PER_MINUTE, default 120/min) |
| Anuncios globales | GET announcements/game, GET announcements/{id} | Público; throttle por IP (GAME_API_PUBLIC_READ_PER_MINUTE) |
| Anuncios por jugador | GET announcements/user | Bearer de sesión (mismo usuario ya validado en login) |
Todo lo demás bajo el grupo
auth.api exige solo Authorization: Bearer (no enviar user_id / game_user_id / platform_user_id en el body).2. Servidor de juego (sin sesión de jugador)
Ejemplos:
| Ruta | Auth |
|---|---|
POST /auth/third-party/login | game_public_token + plataforma |
POST /user/stats/submit-batch | game_secret_token + players[].token |
POST /user/mmr/lookup | game_secret_token |
POST /purchases/external | game_secret_token |
POST /webhooks/idcpayment/games/{id} | Firma HMAC (misma clave por juego) |
POST /webhooks/physical-product/... | HMAC o secret por juego |
POST /server/progression/initialize | Secret + game_id |
3. Qué no hacer
---
Resumen de cambios de endurecimiento
| Tema | Comportamiento |
|---|---|
| Login legacy | Desactivado por defecto (GAME_API_LEGACY_LOGIN_ENABLED) |
/test/ | Solo con GAME_API_DEBUG_ROUTES=true |
EconomÃa debug (add-item, loot grant) | GAME_API_CLIENT_ECONOMY_GRANTS=false en prod |
| Stats / eventos desde cliente | Por juego: Edit Game → Trust client stats (off = solo S2S submit-batch). Env GAME_API_CLIENT_STATS_WRITE = override global (staging) |
| Sandbox | Por juego: Edit Game → Sandbox. Require server secret for sandbox login es opcional y está desmarcado por defecto; sin esa opción basta game_public_token. Si se activa, requiere además game_secret_token desde un backend de confianza. GAME_API_SANDBOX_LOGIN_ENABLED=false bloquea sandbox en todos los juegos |
| Clanes / anuncios por usuario | Scoped al jugador del Bearer |
| Slots | /user/slots/ sin game_user_id en body |
| Webhook fÃsico | Misma clave por juego que IDC Payment (HMAC o secret), ver IDCPAYMENT_PHYSICAL_PRODUCT_WEBHOOK.md |
---
Autenticación de jugador
Sandbox simula identidades sin verificarlas contra una plataforma externa. Mantenerlo habilitado solo durante las pruebas. La opción
platform_configs.sandbox.require_server_secret se interpreta como false también en juegos existentes que aún no tengan ese campo. No requiere migraciones. Las sesiones sandbox permiten probar las mismas operaciones de jugador que las demás plataformas: compras, apertura de cajas, recompensas, inventario inicial y regalos configurados. Se aplican los mismos saldos, requisitos, lÃmites de cobro y controles por juego; sandbox no concede privilegios de servidor.Si se activa la exigencia de secreto, una credencial de servidor ausente o incorrecta devuelve HTTP 401 con
error: sandbox_server_credentials_required y un mensaje especÃfico. El token público sigue siendo obligatorio en ambos modos. No sustituirlo por el secreto ni incluir el secreto de servidor en una build distribuida.Sandbox tiene un lÃmite predeterminado de 32 cuentas por juego, también para juegos existentes sin configuración. En Editar juego → Sandbox,
Sandbox account limit per game permite ajustarlo entre 0 y 10.000; platform_configs.sandbox.user_limit guarda ese valor. Cuenta cuentas, no sesiones simultáneas. Al alcanzar el lÃmite solo se rechazan nuevas cuentas: las existentes pueden seguir entrando y probando todas las funciones. Ponerlo a 0 congela nuevas altas sin deshabilitar el login de cuentas existentes. Bajar el lÃmite no borra cuentas anteriores.Una nueva alta sin plaza devuelve HTTP 409,
error: sandbox_user_limit_reached, message, limit y sandbox_users. No se crea una cuenta ni se entregan premios. La creación y la comprobación del cupo comparten una transacción con bloqueo por juego; se aplica también a altas del panel y a conversiones de otras plataformas a sandbox.Free sandbox account slots, en Editar juego, permite borrar todas las cuentas sandbox de ese juego con confirmación explÃcita. Elimina sus cuentas/progreso de prueba e invalida sus sesiones; no borra usuarios de otras plataformas ni juegos. Conserva métricas históricas agregadas y no revierte intercambios ya completados con terceros. Antes de borrar, hay que transferir clanes de propiedad sandbox que tengan miembros no sandbox y resolver pujas activas que impliquen esas cuentas; si existen, la operación se rechaza completa. Las salas de voz afectadas rotan sus credenciales y usan la cola persistente de revocaciones del proveedor; los participantes restantes pueden necesitar volver a unirse.
POST /api/v1/auth/third-party/login
Content-Type: application/json
{
"game_id": 1,
"game_public_token": "",
"platform": "idc",
"token": "...",
"user_id": "..."
} Respuesta:
access_token / token → usar en todas las llamadas de jugador:Authorization: Bearer Documentación: Platform Login.
---
Stats y progresión (jugador)
Con Bearer únicamente:
POST /user/stats/submitPOST /user/stats/incrementPOST /progression/process-match (usuario = sesión; no suplantar otro platform_user_id)GET /progression/player (solo tu progresión)GET /announcements/user (tras login)Servidor dedicado con muchos jugadores tras partida:
POST /user/stats/submit-batch + secret + tokens de sesión por jugador.---
Inventario y economÃa
buy-item, battle pass, tienda → Bearer.add-item / loot grant / clear: desactivados en prod salvo flag explÃcito de debug.---
Slots de inventario
| Método | Ruta |
|---|---|
| GET | /api/v1/user/slots |
| POST | /api/v1/user/slots/auto-equip |
| POST | /api/v1/user/slots/items/assign |
| POST | /api/v1/user/slots/items/remove |
| POST | /api/v1/user/slots/items/move |
Bearer obligatorio; no enviar
game_user_id.---
Market jugador a jugador (REST)
Prefijo:
/api/v1/market (legacy equivalente /api/market sin v1).Catálogo público (sin login)
| Método | Ruta | Query / notas | ||
|---|---|---|---|---|
| GET | /market/offers | game_id obligatorio (entero). Filtros opcionales: item_type, min_price, max_price, currency_type (coins \ | gems \ | tokens), search, sort_by, sort_order, limit (≤100). Throttle IP: GAME_API_PUBLIC_READ_PER_MINUTE. |
| GET | /market/offers/{id} | game_id obligatorio. Solo ofertas active no caducadas del juego indicado. | ||
| GET | /market/item-types | Tipos de Ãtem para formularios. | ||
| GET | /market/currency-types | Etiquetas de moneda del market. |
Respuesta de listado/detalle: objeto público (
toPublicArray) — sin datos internos del vendedor más allá de id y username.Acciones de jugador (Bearer + game-api.player-identity)
El panel identifica al vendedor/comprador por la sesión; no enviar
game_user_id en el body.| Método | Ruta | Body (JSON) | |||
|---|---|---|---|---|---|
| POST | /market/offers | item_type, item_name, quantity, price, currency_type, item_data.item_variant_id (obligatorio), item_data.attributes opcional, item_description, item_image, expires_at opcional (default ~7 dÃas). El Ãtem se retira del inventario (escrow) al publicar. | |||
| POST | /market/offers/{id}/purchase | vacÃo. Comprador = sesión. Debe tener saldo (coins → game_currency, gems/tokens → premium_currency). Transfiere moneda y entrega el Ãtem. | |||
| POST | /market/offers/{id}/cancel | vacÃo. Solo el vendedor de la sesión. Devuelve escrow. | |||
| GET | /market/my-offers | status (active \ | sold \ | cancelled \ | all), limit. |
| GET | /market/my-purchases | limit. | |||
| GET | /market/statistics | Agregados del juego de la sesión. |
Reglas de negocio
expires_at pasado) dejan de listarse; el operador puede ejecutar php artisan market:expire-offers (también hourly en scheduler) para marcar expired y devolver escrow.game_id que el jugador y is_tradeable si está definido.Ejemplo publicar
POST /api/v1/market/offers
Authorization: Bearer
Content-Type: application/json
{
"item_type": "weapon",
"item_name": "Rare sword",
"quantity": 1,
"price": 100,
"currency_type": "coins",
"item_data": {
"item_variant_id": 42,
"attributes": {}
}
}---
Inicializar progresión de un juego
Solo servidor (no jugador):
POST /api/v1/server/progression/initialize
X-Game-Secret:
{ "game_id": 1, "game_type": "shooter" }La ruta antigua
POST /progression/initialize con Bearer ya no existe.---
Variables .env (operador)
GAME_API_LEGACY_LOGIN_ENABLED=false
GAME_API_DEBUG_ROUTES=false
GAME_API_CLIENT_ECONOMY_GRANTS=false
GAME_API_CLIENT_STATS_WRITE=false
GAME_API_SANDBOX_LOGIN_ENABLED=false
GAME_API_GLOBAL_RATE_PER_MINUTE=600
GAME_API_PUBLIC_READ_PER_MINUTE=120
GAME_API_AUTH_LOGIN_RATE_PER_MINUTE=20php artisan config:cache tras cambios. Detalle de throttling: RATE_LIMITING.md.---
Checklist integrador
/server/*, batch, purchases, webhooks./inventory-slots/* públicas (eliminadas).POST progression/initialize → POST server/progression/initialize con secret.---