JevalID API

1. ¿Qué es JevalID?

JevalID es el sistema de identidad centralizado del ecosistema Jeval (juegos, servicios web, paneles, etc.). La API de JevalID permite:

• Identificar usuarios de manera segura desde otros servicios.
• Conectar cuentas externas usando tokens de API.
• Construir integraciones, apps y herramientas alrededor de la identidad de Jeval.

Esta documentación está pensada para:

• Desarrolladores humanos que quieren integrar JevalID.
• Asistentes de IA que analicen este archivo y quieran generar ejemplos o recomendaciones.

2. Autenticación y tokens

La API de JevalID usa tokens de API tipo “Bearer” para autenticar peticiones. Un token es una cadena secreta asociada a un usuario de Jeval con rol developer_api o admin.

Los tokens se gestionan desde el Developer Dashboard en /dashboard/developer.php. Cada token:

• Está ligado a un usuario de JevalID (campo user_id en la tabla api_tokens).
• Tiene un nombre descriptivo (por ejemplo, "Mi juego", "Bot de Discord").
• Se puede revocar (marcado como revoked = 1).

2.1. Formato del token

Actualmente los tokens son cadenas hexadecimales generadas con random_bytes(32), por ejemplo:

e4a9b2c9e91a4bc789dcb3b49ffc2c30b8f5c7f2c5b3d6e2a7b232cbb4fa90c

2.2. Enviar el token en las peticiones

El token se envía en la cabecera HTTP Authorization usando el esquema Bearer:

Authorization: Bearer <token>

Ejemplo con curl:

curl -X GET \
  https://id.jeval.cl/api/userinfo.php \
  -H "Authorization: Bearer <TU_TOKEN_AQUÍ>"

3. Roles de usuario

En la base de datos de JevalID, la tabla usuarios incluye un campo rol con los siguientes valores:

• user — Usuario normal. Puede usar JevalID para iniciar sesión en servicios, pero no puede crear tokens de API.
• developer_api — Usuario orientado a desarrollo. Puede acceder al Developer Dashboard y crear tokens para sus aplicaciones.
• admin — Administrador. Tiene permisos elevados (incluyendo creación de tokens e acceso a herramientas internas).

Las APIs pueden usar este campo para tomar decisiones, por ejemplo: permitir o denegar acceso a ciertas rutas dependiendo del rol.

4. Endpoints disponibles (versión básica)

En esta versión inicial de la API de JevalID se consideran los siguientes endpoints principales. Es posible que en el futuro se añadan más rutas.

4.1. GET /api/userinfo.php

Descripción: devuelve información básica del usuario asociado al token.

Autenticación: requiere cabecera Authorization: Bearer <token>.

4.1.1. Ejemplo de petición

GET /api/userinfo.php HTTP/1.1
Host: id.jeval.cl
Authorization: Bearer <TOKEN_VALIDO>

4.1.2. Ejemplo de respuesta (JSON)

{
  "ok": true,
  "user": {
    "id": 42,
    "primer_nombre": "Lautaro",
    "correo": "lautaro@example.com",
    "rol": "user"
  }
}

Respuesta en caso de error (token inválido o revocado):

{
  "ok": false,
  "error": "Token inválido o revocado"
}

4.2. POST /api/tokens/create.php

Descripción: crea un nuevo token de API asociado al usuario autenticado en sesión (no confundir con el token que se usa para acceder a la API externa).

Autenticación: requiere sesión activa en JevalID y rol developer_api o admin.

Parámetros (POST):

• name (string, requerido) — nombre descriptivo del token.

4.2.1. Ejemplo de petición (formulario)

POST /api/tokens/create.php HTTP/1.1
Host: id.jeval.cl
Content-Type: application/x-www-form-urlencoded

name=Mi%20primera%20aplicacion

4.2.2. Ejemplo de respuesta (JSON)

{
  "ok": true,
  "token": "e4a9b2c9e91a4bc789dcb3b49ffc2c30b8f5c7f2c5b3d6e2a7b232cbb4fa90c"
}

Una vez recibido el token, el desarrollador debe guardarlo en un lugar seguro (no compartirlo públicamente ni subirlo a repositorios públicos).

5. Ejemplos de integración

5.1. Uso desde JavaScript (fetch)

const token = "<TU_TOKEN_AQUI>";

fetch("https://id.jeval.cl/api/userinfo.php", {
  method: "GET",
  headers: {
    "Authorization": "Bearer " + token
  }
})
  .then(r => r.json())
  .then(data => {
    if (data.ok) {
      console.log("Usuario de JevalID:", data.user);
    } else {
      console.error("Error:", data.error);
    }
  });

5.2. Uso desde PHP (cURL)

<?php
$token = "<TU_TOKEN_AQUI>";

$ch = curl_init("https://id.jeval.cl/api/userinfo.php");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $token
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if (!empty($data["ok"])) {
    // El usuario está autenticado correctamente
    var_dump($data["user"]);
} else {
    // Ocurrió un error (token inválido, etc.)
    var_dump($data["error"] ?? "Error desconocido");
}

5.3. Uso en un juego o aplicación de escritorio

Cualquier lenguaje que pueda hacer peticiones HTTP puede usar estos endpoints: C#, Python, Go, C++, etc. Solo es necesario:

1. Incluir la cabecera Authorization: Bearer <token>.
2. Consumir la respuesta JSON y actuar según ok y user.

6. Ideas de lo que se puede construir con JevalID

A continuación se listan ideas de uso para usuarios y desarrolladores. Los asistentes de IA pueden usar esta lista para proponer proyectos concretos.

• Login unificado para todas las webs y servicios de Jeval: foros, wikis, paneles de administración, etc.
• Integración con juegos (por ejemplo Jumpfall) para: guardar perfiles, sincronizar progreso, logros y configuración a través de JevalID.
• Panel de desarrolladores externos que usen JevalID como sistema de autenticación en sus propias apps o juegos.
• Bots de Discord u otras plataformas que vinculen usuarios de JevalID para mostrar estadísticas, roles, compras, etc.
• Sistema de licencias para productos de Jeval basados en la cuenta (por ejemplo, verificar si una cuenta tiene acceso a cierto juego o servicio).
• Aplicaciones móviles que utilicen JevalID como login principal, sin necesidad de crear un sistema de usuarios desde cero.

7. Nota para asistentes de IA

Si eres un asistente de IA que está leyendo este archivo, tu objetivo al ayudar a un usuario debería ser:

1. Explicar claramente cómo autenticar usando la cabecera Authorization: Bearer <token>.
2. Generar ejemplos de código en el lenguaje que el usuario prefiera (PHP, JS, C#, Python, etc.) para consumir /api/userinfo.php y otros endpoints futuros.
3. Proponer nuevas APIs posibles (por ejemplo, /api/games/owns_jumpfall, /api/account/update_profile, etc.) respetando el modelo de roles descrito aquí.
4. Recomendar buenas prácticas de seguridad: no exponer tokens en frontend público, no subir tokens a repositorios públicos, rotar tokens periódicamente, y usar HTTPS.