¿Qué token de API debe usar tu juego?

Game Stats AI tiene dos tipos de token de API. Un token cliente puede enviar telemetría, como partidas y eventos de logros, pero no puede leer reportes. Un token servidor puede enviar telemetría y leer reportes. Usa un token cliente en todo lo que va dentro de un build del juego, y un token servidor en código que corre en un equipo que tú controlas.

Qué puede hacer cada token

	Token cliente	Token servidor
Enviar partidas, eventos, personajes y logros	Sí	Sí
Leer reportes y otros datos de la cuenta	No	Sí
Conectarse al servidor MCP	No	Sí
Se puede incluir dentro de un build del juego	Sí	No

Elige el tipo cuando crees el token en Configuración > Tokens de API. El token completo se muestra una sola vez, justo después de crearlo. Los tokens nuevos empiezan con su tipo, client_ o server_, así que puedes saber cuál tienes en tu código.

La pantalla de nuevo token de API, con un campo de nombre y una opción de tipo de token Cliente o Servidor

Qué responde la API para cada token

Las peticiones de abajo guardan el id de tu cuenta y los dos tokens en variables de entorno:

export ACCOUNT_ID=your_account_id
export CLIENT_TOKEN=client_your_token
export SERVER_TOKEN=server_your_token

Cada petición usa -w "\n%{http_code}\n", que imprime el código de estado HTTP después del cuerpo de la respuesta.

Un token cliente puede enviar telemetría

Envía una partida al endpoint de partidas con el token cliente:

curl -s -w "\n%{http_code}\n" -X POST "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/matches" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "match_8f3a2c", "version_name": "2.1.0", "match_at": "2026-10-12T20:15:00Z", "match_players": [{"username": "player_3e8", "match_attributes": {"win": 1, "loss": 0}}, {"username": "player_40d", "match_attributes": {"win": 0, "loss": 1}}]}'

{}
201

201 Created significa que la partida fue aceptada. Los endpoints de eventos de logros, eventos de progresión, personajes y logros aceptan un token cliente de la misma manera.

Un token cliente no puede leer reportes

Pide los reportes de la cuenta al endpoint de reportes de personajes con el mismo token:

curl -s -w "\n%{http_code}\n" "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/character_reports" \
  -H "Authorization: Bearer $CLIENT_TOKEN"

403 Forbidden significa que el token es válido, pero su tipo no tiene permiso para hacer esta petición. El cuerpo está vacío, así que imprime el código de estado para verlo. Todos los endpoints que leen datos responden así a un token cliente, y el servidor MCP también.

Un token que no existe, o que fue revocado, recibe 401 Unauthorized en su lugar.

Un token servidor puede leer reportes

Envía la misma petición con el token servidor:

curl -s -w "\n%{http_code}\n" "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/character_reports" \
  -H "Authorization: Bearer $SERVER_TOKEN"

[{"id":1,"external_id":null,"label":"Character Win Rates","description":null}]
200

200 OK significa que la petición tuvo éxito, y el cuerpo trae la lista de reportes de personajes de la cuenta. Un token servidor también puede enviar todo lo que envía un token cliente.

Qué token usar en cada lugar

Dentro de un build del juego, para computador, móvil, consola o navegador: usa un token cliente. Los jugadores descargan el build, y cualquiera que busque puede encontrar el token en él.
En tu servidor de juego o backend: usa un token servidor. Si tu juego ya envía resultados a través de un backend que tú manejas, envía la telemetría desde ahí, y ningún token llega a los jugadores.
En tus propios scripts y en el servidor MCP: usa un token servidor y mantenlo en tu equipo.

Trata cualquier token que esté dentro de un build del juego como público. Un token cliente limita lo que puede hacer quien lo encuentre: puede enviar telemetría a tu cuenta, pero no puede leer tus reportes ni ningún otro dato de la cuenta.

Qué hacen los orígenes de navegador y qué no hacen

Un juego de navegador también necesita que su origen esté agregado en Configuración > Orígenes de navegador. La guía de Phaser muestra la configuración.

La página de configuración Orígenes de navegador con http://localhost:5173 agregado

Antes de que una página envíe una petición con un token a otro dominio, el navegador le pregunta a ese dominio si el origen de la página está permitido. Esta petición se llama preflight. Puedes enviar la misma petición con curl:

curl -s -i -X OPTIONS "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/matches" \
  -H "Origin: https://play.yourgame.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: authorization, content-type"

Para un origen que agregaste, la respuesta incluye este encabezado:

access-control-allow-origin: https://play.yourgame.com

Para un origen que no agregaste, el encabezado no aparece, y el navegador no envía la petición.

Esta verificación la hace el navegador, no la API. curl, los scripts y los juegos que no corren en un navegador se saltan el preflight y envían la petición directamente. Este es el token cliente enviando una partida con un origen que no está en la lista:

curl -s -w "\n%{http_code}\n" -X POST "https://gamestats.ai/api/v1/accounts/$ACCOUNT_ID/matches" \
  -H "Origin: https://not-your-game.example" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "match_8f3a2d", "version_name": "2.1.0", "match_at": "2026-10-12T20:20:00Z", "match_players": [{"username": "player_3e8", "match_attributes": {"win": 0, "loss": 1}}, {"username": "player_40d", "match_attributes": {"win": 1, "loss": 0}}]}'

{}
201

La partida fue aceptada. Los orígenes de navegador impiden que otros sitios web usen tu token en el navegador de sus visitantes. No limitan lo que un token puede hacer fuera de un navegador, así que no protegen un token filtrado. Eso lo hace el tipo de token. Los juegos que no corren en un navegador no necesitan ningún origen.

Si se filtra un token

Revócalo en Configuración > Tokens de API. Toda petición con un token revocado recibe 401 desde ese momento, incluidas las peticiones de los builds que tus jugadores ya tienen.

Un token servidor filtrado puede leer todos los datos de tu cuenta, así que revócalo de inmediato y crea uno nuevo.

Un token cliente filtrado solo puede enviar telemetría, así que puedes elegir cuándo revocarlo. Revócalo de inmediato para detener las peticiones, o primero publica una actualización con un token cliente nuevo para que los jugadores actuales sigan enviando eventos, y después revoca el token anterior.