Xsolla-logo

Descripción general

Esta sección describe las llamadas API para trabajar con Login. Establezca su proyecto de Login en Cuenta del editor antes de enviar solicitudes.

IP addresses

The full list of IP addresses that login.xsolla.com may use:

  • 34.94.0.85
  • 34.94.14.95
  • 34.94.25.33
  • 34.94.115.185
  • 34.94.154.26
  • 34.94.173.132
  • 34.102.48.30
  • 35.235.99.248
  • 35.236.32.131
  • 35.236.35.100
  • 35.236.117.164

Descargar definición de API

Puede descargar la definición de API en dos formatos:

Glosario

Puede acceder a los siguientes tipos de proyectos de Login en Cuenta del editor:

  • Proyecto de Login estándar
  • Proyecto de Login concurrente

Para obtener más información al respecto, consulte el artículo Cuenta multiplataforma.

Límites de frecuencia

Son las restricciones aplicadas por la API de Xsolla a la frecuencia de acceso por parte de un usuario en un plazo definido.

Proyecto de Login estándar

Es un proyecto de Login que se utiliza para almacenar las cuentas principales.

Proyecto de Login concurrente

Es un proyecto de Login que se utiliza para almacenar las cuentas de plataforma.

Cuenta principal

Es un tipo de cuenta que se crea en un proyecto de Login estándar y se vincula a cuentas de plataforma. La cuenta principal se utiliza para identificar al jugador en las diferentes plataformas.

Cuenta de plataforma

Es un tipo de cuenta que se crea en un proyecto de Login concurrente y se conecta a una plataforma de publicación definida. La cuenta de plataforma no puede vincularse a otra cuenta de plataforma. Tampoco puede desvincularse de una cuenta principal.

Plataforma de publicación

Es una plataforma de juegos que se utiliza para la distribución de juegos (p.  ej., Steam, PlayStation, Xbox, etc.).

Autenticación

Login API admite los siguientes tipos de token:

Authentication schemes

Puede determinar si una llamada API es del lado del cliente o del lado del servidor por el esquema de autenticación:

  • Client-side — are called without authentication or with the Authorization header: Bearer <user_JWT> header, where <user_JWT> — is the user token.
  • Server-side API calls for implementing the user flow — are called with the header: X-SERVER-AUTHORIZATION: <server_JWT>, where <server_JWT> — is the server token.

Obtener un token de usuario

Para obtener el token, envíe una de las siguientes solicitudes:

Tras la autenticación mediante JWT, el usuario es redirigido a la URL de devolución de llamada con un token en un parámetro de consulta: <Callback URL>?token=<User token (JWT)>.

Tras la aunticación basada en el protocolo OAuth 2.0, envíe la solicitud Generate JWT al servidor de Xsolla Login para cambiar el parámetro code recibido por un token de usuario (access_token).

Obtener un token de servidor

Para obtener un token de servidor:

  1. Establezca el servidor cliente de OAuth 2.0.
  2. Genere un JWT de servidor.

Establecer el cliente de OAuth 2.0

  1. Abra su proyecto en Cuenta del editor y vaya a la sección de Login.
  2. Haga clic en Configure en el panel de un proyecto de Login.
  3. Vaya al bloque Security y seleccione la sección OAuth 2.0.
  4. Haga clic en Add OAuth 2.0 Client.
  5. Marque la casilla Server (server-to-server connection).
  6. Especifique Token lifetime.
  7. Haga clic en Connect.
  8. Copie y guarde el ID de cliente y la clave secreta.

Generar un JWT de servidor

En el back-end de su aplicación, implemente un método para obtener el JWT de servidor utilizando la llamada Generate JWT API. La solicitud debe contener los siguientes parámetros:

  • grant_type es el tipo de obtención del JWT, transmita el valor client_credentials.
  • client_secret es la clave secreta que se recibe cuando establece el cliente de OAuth 2.0 del servidor.
  • client_id es el ID de cliente recibido al establecer el cliente OAuth 2.0 del servidor.

Límites de frecuencia

Para evitar sobrecargas del sistema de Xsolla y protegerlo de ráfagas repentinas de tráfico entrante, Xsolla limita el número de solicitudes recibidas por la API de Xsolla durante un periodo especificado. Si se excede el límite, la API de Xsolla devuelve una respuesta HTTP con el código de estado 429.

Rate limits vary by method, IP-address, authentication scheme, and other factors.

Rate limits for server-side methods are applied to methods with server-side authentication — methods that are called with the X-SERVER-AUTHORIZATION: <server_JWT> header, where <server_JWT> is the server token.

Rate limits for client-side methods are applied to methods without authentication or with client-side authentication — methods that are called with the Authorization: Bearer <user_JWT> header, where <user_JWT> is the user token.

Example of a method with server-side authentication: Example of a 
method with server-side 
authentication Example of a method with client-side authentication: Example of a method with server-side 
authentication

Los límites de frecuencia para los métodos del lado del cliente no cambian y son necesarios para impedir ataques de fuerza bruta. La frecuencia máxima de solicitudes para los métodos del lado del servidor es mayor que para los métodos del lado del cliente. Puede consultar las recomendaciones sobre cómo gestionar los límites de frecuencia en la documentación.

Observación En determinados casos, pueden ajustarse los límites de frecuencia previa solicitud. Para solicitar el ajuste de los límites de frecuencia, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

Estructura del JWT

Cada token tiene un formato de JWT y contiene una información precisa en una carga útil.

Usuario de JWT

El JWT de usuario es un token recibido como resultado de una autenticación o registro. La carga útil de un token contiene información sobre el usuario y la llamada de autenticación.

Obtener un token de usuario mediante el protocolo OAuth 2.0 requiere un cliente de OAuth 2.0. El token de usuario se transmite en el encabezado Authorization: Bearer <JWT>.

Principales notificaciones

Un token contendrá las notificaciones principales tras la autenticación o la confirmación de la dirección de correo electrónico. La presencia de estas notificaciones no depende de la base de datos de usuarios ni de la llamada de autenticación.

 
Notificación Tipo Obligatoria Descripción
exp Marca de tiempo de Unix Fecha y hora de expiración del token. El tiempo de expiración por defecto es de 24 horas. Puede cambiar el tiempo de expiración para cada proyecto de Login.
iss string Servicio que firmó el token: https://login.xsolla.com.
iat Marca de tiempo de Unix Fecha y hora de entrega del token.
sub string (cadena) (UUID) ID de usuario escrito en el lado del servidor de Xsolla Login.
groups matriz

La lista de grupos a los que pertenece el usuario. Cada grupo se escribe con el siguiente formato:

  • id - ID del grupo
  • name - nombre del grupo
  • is_default - muestra si se trata de un grupo por defecto o no (valores true o false ).

Solo puede haber un grupo por defecto. Este grupo incluye inicialmente a todos los usuarios antes de que se distribuyan en diferentes grupos.

xsolla_login_project_id string (cadena) (UUID) ID del proyecto de Login.
type string

Opciones de autenticación:

  • xsolla_login - inicio de sesión mediante nombre de usuario/correo electrónico y contraseña.
  • social - inicio de sesión mediante redes sociales
  • email - inicio de sesión sin contraseña mediante código de un solo uso recibido por correo electrónico.
  • phone - inicio de sesión sin contraseña mediante un código de un solo uso recibido por SMS.
  • firebase - inicio de sesión mediante nombre de usuario/correo electrónico y contraseña cuando el almacenamiento de datos del usuario es Firebase.
  • playfab - Inicio de sesión mediante nombre de usuario/correo electrónico y contraseña cuando el almacenamiento de datos del usuario es PlayFab.
  • proxy - inicio de sesión a través de nombre de usuario / correo electrónico y contraseña cuando el almacenamiento de datos de usuario es personalizado.
  • device - inicio de sesión con ID de dispositivo.
  • server_custom_id - inicio de sesión con ID personalizado.

Solo puede haber un grupo por defecto. Este grupo incluye inicialmente a todos los usuarios antes de que se distribuyan en diferentes grupos.

avatar string URL del avatar del usuario.
username string Nombre de usuario.
publisher_id integer ID de un vendedor propietario de un proyecto de Login.
email string Dirección de correo electrónico del usuario.
payload string Información adicional que se transmite en el parámetro de carga útil durante la autenticación.
promo_email_agreement boolean

Puede tener uno de los siguientes valores:

  • true si el usuario acepta recibir un boletín.
  • false en caso contrario.
Tiene el valor true por defecto.

Para añadir la función al formulario de registro del widget de Login :

  • Contacte con su gestor de cuenta si utiliza el widget 2.0.
  • Agregue el parámetro fields con el valor promo_email_agreement al código de inicialización si utiliza la versión anterior del widget.

connection_information string Muestra si el usuario ha confirmado o no su fecha de nacimiento. La confirmación se realiza a través del servicio okname.

Almacenamiento PlayFab

Notificaciones contenidas en el token tras la autenticación si utiliza el almacenamiento de PlayFab.

Notificación Tipo Obligatoria Descripción
external_account_id string ID de usuario de PlayFab.
session_ticket string

Un parámetro SessionTicket recibido durante una solicitud de autenticación o solicitudes a la PlayFab API.

Un token contiene la notificación si autentica a los usuarios mediante el protocolo OAuth 2.0 y transmite el valor playfab al parámetro scope.

entity_token string Un parámetro EntityToken.EntityToken.
entity_type string Un parámetro EntityToken.Entity.Type. Solo puede tener el valor title_player_account.
entity_id string Un parámetro EntityToken.Entity.Id.

Almacenamiento personalizado

Notificaciones contenidas en el token tras la autenticación si utiliza el almacenamiento personalizado.

Notificación Tipo Obligatoria Descripción
provider string Nombre de la red social utilizada para la autenticación. Si el usuario se autentica mediante nombre de usuario y contraseña, la notificación tiene el valor xsolla.
external_account_id string ID de usuario en el lado de su servidor.
partner_data Datos de cualquier tipo devueltos por su servidor en el cuerpo de la respuesta durante la autenticación.

Autenticación mediante redes sociales

Notificaciones contenidas en el token tras la autenticación a través de una red social. La presencia de estas notificaciones no depende de la base de datos de usuarios.

Notificación Tipo Obligatoria Descripción
provider string Nombre de la red social utilizada para la autenticación.
id string ID de usuario en una red social.
is_cross_auth boolean Muestra que la solicitud de autenticación silenciosa está en curso.
social_access_token string Parámetro access_token de la cuenta de red social utilizado para la autenticación. Póngase en contacto con su gestor de cuenta para establecer esta función.
picture string (URL) Enlace a la foto de perfil del usuario en una red social.
birthday fecha (RFC3339) Fecha de nacimiento del usuario en una red social.
gender string Sexo/género de los usuarios en una red social.
name string Apodo del usuario en una red social.

Autenticación mediante el protocolo OAuth 2.0

Notificaciones contenidas en el token tras la autenticación OAuth 2.0.

Notificación Tipo Obligatoria Descripción
jti string ID de token único.

Autenticación mediante un número de teléfono

Notificación que contiene el token tras la autenticación mediante un número de teléfono.

Notificación Tipo Obligatoria Descripción
phone_number string Número de teléfono del usuario utilizado para la autenticación. El formato del número de teléfono se basa en el código de país, el distintivo de zona y el número de línea sin separadores.

JWT del servidor

El token del servidor se transmite en el encabezado X-SERVER-AUTHORIZATION.

La carga útil del token contiene información sobre los recursos que posee el cliente de OAuth 2.0. El token tiene acceso a llamadas con autenticación basada en servidor para estos recursos.

Notificación Tipo Obligatoria Descripción
xsolla_login_project_id string (cadena) (UUID) ID de un proyecto de Login que posee el cliente de OAuth 2.0.
resources matriz

Lista de recursos propiedad de un cliente de OAuth 2.0. Posibles tipos de recursos:

  • publisher_id - recursos de un vendedor propietario del proyecto de Login
  • publisher_project_id - recursos de un proyecto en Cuenta del editor.

Cada grupo se escribe en el siguiente formato:

  • name - tipo de recurso
  • value - ID del recurso

jti string ID de token único.

Validación del JWT

Tras una autenticación correcta, se genera un JWT para cada usuario. El JWT generado está firmado mediante una clave secreta. Para asegurarse de que un JWT es relevante y pertenece al usuario de su proyecto de Login, debe validar su valor.

Para validar un JWT:

  1. Abra su proyecto en Cuenta del editor y vaya a la sección Login.
  2. Haga clic en Configure en el panel de una opción de Login.
  3. En la página de navegación, vaya al bloque Security y seleccione la sección JWT Signature.
  4. Seleccione su método de cifrado y copie el valor del campo Secret key o New public JSON Web Key, en función del método seleccionado.
  5. Elija la biblioteca y conéctela en el lado del servidor de su aplicación.
  6. Transmita el valor, copiado en el paso 4, a la entrada de la función de validación.

Aviso

No revele su clave secreta a nadie. Si se ha visto comprometida, cámbiela.

Errores

En caso de respuestas de error, el servidor Xsolla Login devuelve un objeto JSON con los siguientes campos:

Campo Tipo Descripción
código string Código de error del servidor de Xsolla Login.
descripción string Descripción del error. El texto está siempre en inglés. No utilice este texto en caso de error, ya que el valor puede cambiar en el futuro.
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

Solicitud errónea 400

Código Descripción
0 La solicitud tiene parámetros no válidos.
010-019 Falló la autenticación del cliente (p. ej., cliente desconocido, no se incluyó la autenticación del cliente o el método de autenticación no es compatible).
010-022 Falta el estado del parámetro o es demasiado débil, ya que tiene menos de 8 caracteres.
010-023 La concesión de autorización o el token de actualización no es válido, ha expirado, ha sido revocado, no coincide con el URL de redireccionamiento usado en la solicitud de autorización o se ha emitido para otro cliente.

401 No autorizado

Código Descripción
002-016 Token no válido.
002-040 No se pudo autorizar al usuario prohibido.
003-001 Nombre de usuario o contraseña incorrecto.
003-007 Cuenta de usuario no confirmada.
003-025 Se produjo un error al obtener el token de acceso de OAuth 2.0.
003-040 Usuario no autorizado.
010-026 El servidor de Xsolla Login o el propietario del recurso denegaron la solicitud.

403 Prohibido

Código Descripción
1901-0001 Token no válido.

404 No encontrado

Código Descripción
003-002 Usuario no encontrado.
003-019 Proyecto no encontrado.
003-061 Objeto no encontrado.

418 I’m a teapot (Soy una tetera)

Código Descripción
004-001 Se ha producido un error.

422 Entidad no procesable

Código Descripción
0 Alias omitido en la consulta.
002-050 No cambió la configuración de autenticación del usuario de dos factores.
003-003 El usuario con el nombre de usuario especificado ya existe.
003-020 Llamada no disponible para este proyecto de Login.
003-022 Este proyecto de Login está mal configurado. Cambie la configuración de este proyecto de Login en la Cuenta del editor de Xsolla o póngase en contacto con el gestor de su cuenta.
003-033 El tipo de proyecto no coincide.
006-003 Los clientes de OAuth 2.0 con el tipo de concesión client_credentials solo pueden tener lista de acceso.
010-015 Fallo en la autenticación mediante red social: SERVICE_NAME.
010-016 Esta cuenta de red social ya está vinculada a otro usuario.
010-032 La autenticación mediante esta red social no está habilitada para este proyecto de Login. Habilítela en su Cuenta del editor de Xsolla > Login > your Login project > Social connections.
030-024 Restablecimiento de contraseña deshabilitado para este proyecto de Login.
2002-0001 Atributos duplicados.

429 Demasiadas solicitudes

Código Descripción
002-054 Se superó el número permitido de intentos de búsqueda. Espere un segundo antes de realizar la siguiente solicitud.
010-005 Se superó el número de solicitudes permitido.
1900-0001 Se superó el número de solicitudes permitido.