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/login o legacy) con game_public_token (prefijo gpp_…, 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.


  • 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)



    CredencialDónde vivePara qué¿En el cliente del juego?
    game_public_token (gpp_…)Edit Game → Public tokenDemostrar 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 BearerRespuesta de loginIdentidad 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_tokenEdit Game → Server secretSolo 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)



    TipoEjemplosAuth
    LoginPOST auth/third-party/logingame_public_token + plataforma
    RefreshPOST auth/refreshrefresh_token
    Stats S2SPOST user/stats/submit-batchgame_secret_token + players[].token
    MMR lookupPOST user/mmr/lookupgame_secret_token
    Tienda externaPOST purchases/external, webhooks IDCgame_secret_token o HMAC
    BootstrapPOST server/progression/initializegame_secret_token
    Market browseGET /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 globalesGET announcements/game, GET announcements/{id}Público; throttle por IP (GAME_API_PUBLIC_READ_PER_MINUTE)
    Anuncios por jugadorGET announcements/userBearer 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)



  • game_id + game_secret_token (alias API del valor almacenado como gamepanel_secret_token en 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)


  • Ejemplos:

    RutaAuth
    POST /auth/third-party/logingame_public_token + plataforma
    POST /user/stats/submit-batchgame_secret_token + players[].token
    POST /user/mmr/lookupgame_secret_token
    POST /purchases/externalgame_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/initializeSecret + game_id

    3. Qué no hacer



  • Embeber game_secret_token / server secret en el .exe / APK (usa solo game_public_token para login).

  • Enviar el secret en cada POST user/stats/submit o progression/process-match con Bearer (ya no se exige ni se debe usar).


  • ---

    Resumen de cambios de endurecimiento



    TemaComportamiento
    Login legacyDesactivado 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 clientePor juego: Edit Game → Trust client stats (off = solo S2S submit-batch). Env GAME_API_CLIENT_STATS_WRITE = override global (staging)
    SandboxPor 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 usuarioScoped al jugador del Bearer
    Slots/user/slots/ sin game_user_id en body
    Webhook físicoMisma 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/submit

  • POST /user/stats/increment

  • POST /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



  • Compras normales: buy-item, battle pass, tienda → Bearer.

  • add-item / loot grant / clear: desactivados en prod salvo flag explícito de debug.


  • ---

    Slots de inventario



    MétodoRuta
    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étodoRutaQuery / notas
    GET/market/offersgame_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-typesTipos de ítem para formularios.
    GET/market/currency-typesEtiquetas 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étodoRutaBody (JSON)
    POST/market/offersitem_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}/purchasevacío. Comprador = sesión. Debe tener saldo (coins → game_currency, gems/tokens → premium_currency). Transfiere moneda y entrega el ítem.
    POST/market/offers/{id}/cancelvacío. Solo el vendedor de la sesión. Devuelve escrow.
    GET/market/my-offersstatus (active \sold \cancelled \all), limit.
    GET/market/my-purchaseslimit.
    GET/market/statisticsAgregados del juego de la sesión.

    Reglas de negocio



  • Ofertas caducadas (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.

  • Variante debe ser del mismo game_id que el jugador y is_tradeable si está definido.

  • No se puede comprar la propia oferta ni cruzar juegos.


  • 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=20


    php artisan config:cache tras cambios. Detalle de throttling: RATE_LIMITING.md.

    ---

    Checklist integrador



  • [ ] Secret solo en servidor de login y rutas /server/*, batch, purchases, webhooks.

  • [ ] Cliente solo guarda y envía session token.

  • [ ] No usar /inventory-slots/* públicas (eliminadas).

  • [ ] Migrar POST progression/initialize → POST server/progression/initialize con secret.


  • ---

    Más documentación



  • SECURITY_AUDIT_2026-10.md

  • IDC_PAYMENT_CALLBACK.md

  • IDCPAYMENT_PHYSICAL_PRODUCT_WEBHOOK.md