Xsolla-logo

Présentation

Cette section décrit les appels API pour interagir avec Login. Configurez votre projet de connexion dans le Compte éditeur avant d'envoyer des requêtes.

Télécharger la définition API

Vous pouvez télécharger la définition de l'API dans deux formats :

Glossaire

Vous avez accès aux types de projets de connexion suivants dans le Compte éditeur :

  • Projet de connexion standard
  • Projet de connexion fantôme

Pour plus d'informations, voir la fonctionnalité Compte multiplateforme.

Limites de fréquence

Il s'agit des restrictions appliquées par l'API Xsolla à la fréquence d'accès par un utilisateur au cours d'une période définie.

Projet de connexion standard

Il s'agit d'un projet de connexion utilisé pour stocker les comptes principaux.

Projet de connexion fantôme

Il s'agit d'un projet de connexion utilisé pour stocker les comptes de plateformes.

Compte principal

Il s'agit d'un type de compte créé dans un projet de connexion standard et lié aux comptes des plateformes. Le compte principal est utilisé pour identifier le joueur sur différentes plateformes.

Compte de plateforme

Il s'agit d'un type de compte créé dans un projet de connexion fantôme et associé à une plateforme de publication spécifique. Le compte de plateforme ne peut pas être lié à un autre compte de plateforme. De même, vous ne pouvez pas dissocier les comptes d'un compte principal.

Plateforme de publication

Il s'agit d'une plateforme de jeu utilisée pour la distribution des jeux (par exemple Steam, PlayStation, Xbox, etc.).

Authentification

Login API prend en charge les types de jetons suivants :

Obtenir un jeton utilisateur

Pour obtenir le jeton, envoyez l'une des requêtes suivantes :

Après l'authentification JWT, l'utilisateur est redirigé vers l'URL de rappel avec le jeton inclus dans le paramètre de la requête : <Callback URL>?token=<User token (JWT)>.

Après l'authentification basée sur le protocole OAuth 2.0, envoyez la requête Générer un JWT au serveur Xsolla Login pour échanger le paramètre code reçu contre un jeton utilisateur (access_token).

Obtenir un jeton de serveur

Pour obtenir un jeton de serveur :

  1. Configurez le client OAuth 2.0 du serveur.
  2. Générez le JWT du serveur.

Configurer le client OAuth 2.0 du serveur

  1. Ouvrez votre projet dans le Compte éditeur et accédez à la section Login.
  2. Dans le panneau d'un projet de connexion, cliquez sur Configure.
  3. Accédez au bloc Security et sélectionnez la section OAuth 2.0.
  4. Cliquez sur Add OAuth 2.0 Client.
  5. Cochez la case Server (server-to-server connection).
  6. Spécifiez la durée de vie Token lifetime.
  7. Cliquez sur Connect.
  8. Copiez et enregistrez l'ID client et la clé secrète.

Générer le JWT du serveur

Côté client de votre application, implémentez une méthode pour obtenir le JWT du serveur en utilisant l'appel Générer une API JWT. La requête doit contenir les paramètres suivants :

  • grant_type est le type de JWT obtenu, passez la valeur client_credentials.
  • client_secret est la clé secrète obtenue lors de la configuration du client OAuth 2.0 du serveur.
  • client_id est l'ID client obtenu lors de la configuration du client OAuth 2.0 du serveur.

Limites de fréquence

Pour éviter de surcharger le système Xsolla et prévenir les pics soudains de trafic entrant, Xsolla limite le nombre de requêtes reçues par l'API Xsolla au cours d'une période donnée. Si la limite est dépassée, l'API Xsolla renvoie une réponse HTTP avec le code d'état 429.

Les limites de fréquence varient en fonction de la méthode, de l'adresse IP, du type d'autorisation et d'autres facteurs.

Les limites de fréquence pour les méthodes côté serveur s'appliquent aux méthodes avec autorisation côté serveur, c'est-à-dire celles appelées avec l'en- tête X-SERVER-AUTHORIZATION: <server_JWT>, où <server_JWT> est le jeton du serveur.

Les limites de fréquence pour les méthodes côté client s'appliquent aux méthodes sans autorisation ou avec autorisation côté client, c'est-à-dire celles appelées avec l'en-tête Authorization: Bearer <user_JWT>, où <user_JWT> est le jeton d'utilisateur.

Exemple de méthode avec autorisation côté serveur :Exemple de méthode 
avec autorisation côté 
serveur Exemple de méthode avec autorisation côté client  :Exemple de méthode avec autorisation côté 
serveur

Les limites de fréquence pour les méthodes côté client restent inchangées et sont essentielles pour prévenir les attaques par force brute. En revanche, la fréquence maximale des requêtes pour les méthodes côté serveur est plus élevée que celle des méthodes côté client. Pour des recommandations sur la gestion des limites de fréquence, consultez la documentation .

Note Dans certains cas, il est possible d'ajuster les limites de fréquence sur demande. Pour demander l'ajustement des limites de fréquence, contactez votre responsable de la réussite client ou envoyez un e-mail àcsm@xsolla.com.

Structure JWT

Chaque jeton est au format JWT et contient une information précise dans une charge utile.

JWT utilisateur

Le JWT utilisateur est un jeton obtenu à la suite d'une authentification ou d'un enregistrement. Il contient des informations sur l'utilisateur et des données sur l'appel d'authentification

L'obtention d'un jeton utilisateur via le protocole OAuth 2.0 nécessite un client OAuth 2.0. Le jeton utilisateur est passé dans l'en-tête Authorization: Bearer <JWT>.

Revendications principales

Un jeton contient les revendications principales après l'authentification ou la confirmation de l'adresse e-mail. La présence de ces revendications ne dépend pas de la base de données utilisateur ni de l'appel d'authentification.

 
Revendication Type Obligatoire Description
exp Horodatage Unix Oui Date et heure d'expiration du jeton. Par défaut, le délai d'expiration est de 24 heures, mais il est modifiable pour chaque projet de connexion.
iss string Oui Service qui a signé le jeton : https://login.xsolla.com.
iat Horodatage Unix Oui Date et heure de la remise du jeton.
sub string (UUID) Oui ID de l'utilisateur enregistré côté serveur Xsolla Login.
groups array Oui

La liste des groupes dont fait partie l'utilisateur. Chaque groupe est écrit au format suivant :

  • id — ID du groupe ;
  • name — nom du groupe ;
  • is_default — indique si le groupe est la valeur par défaut ou non (valeurs possibles : true ou false).

Il ne peut y avoir qu'un seul groupe par défaut. Ce groupe comprend initialement tous les utilisateurs avant qu'ils ne soient répartis dans différents groupes.

xsolla_login_project_id string (UUID) Oui ID du projet de connexion.
type string

Option d'authentification :

  • xsolla_login — connexion par nom d'utilisateur/adresse e-mail et mot de passe ;
  • social — connexion via les réseaux sociaux ;
  • email — connexion sans mot de passe à l'aide d'un code à usage unique envoyé par e-mail ;
  • phone — connexion sans mot de passe à l'aide d'un code à usage unique envoyé par SMS ;
  • firebase — connexion par nom d'utilisateur/adresse e-mail et mot de passe lorsque le stockage des données utilisateur est Firebase ;
  • playfab — connexion par nom d'utilisateur/adresse e-mail et mot de passe lorsque le stockage des données utilisateur est PlayFab ;
  • proxy — connexion par nom d'utilisateur/adresse e-mail et mot de passe lorsque le stockage des données utilisateur est personnalisé ;
  • device — connexion par ID d'appareil ;
  • server_custom_id — connexion par custom ID.

Il ne peut y avoir qu'un seul groupe par défaut. Ce groupe comprend initialement tous les utilisateurs avant qu'ils ne soient répartis dans différents groupes.

avatar string URL de l'avatar de l'utilisateur.
username string Nom d'utilisateur.
publisher_id integer ID du commerçant, propriétaire du projet de connexion.
email string Adresse e-mail de l'utilisateur.
payload string Informations supplémentaires passées dans le paramètre de charge utile lors de l'authentification.
promo_email_agreement boolean

Valeurs possibles :

  • true si l'utilisateur accepte de recevoir la newsletter ;
  • false dans le cas contraire.
La valeur par défaut est true.

Pour ajouter cette fonctionnalité au formulaire d'enregistrement du widget Login :

  • Contactez votre responsable de compte si vous utilisez le Widget 2.0 ;
  • Ajoutez le paramètre fields avec la valeur promo_email_agreement au code d'initialisation si vous utilisez la version précédente du widget.

connection_information string Indique si l'utilisateur a confirmé ou non sa date de naissance. La confirmation se fait via le service okname.

Stockage PlayFab

Revendications contenues dans le jeton après l'authentification si vous utilisez le stockage PlayFab.

Revendication Type Obligatoire Description
external_account_id string Oui ID PlayFab de l'utilisateur.
session_ticket string Oui

Paramètre SessionTicket reçu lors d'une requête d'authentification ou lors des requêtes à PlayFab API.

Le jeton contient cette revendication si vous authentifiez les utilisateurs via le protocole OAuth 2.0 et que vous passez la valeur playfab au paramètre scope.

entity_token string Oui Paramètre EntityToken.EntityToken.
entity_type string Oui Paramètre EntityToken.Entity.Type. Unique valeur possible title_player_account.
entity_id string Oui Paramètre EntityToken.Entity.Id.

Stockage personnalisé

Revendications contenues dans le jeton après l'authentification si vous utilisez un stockage personnalisé.

Revendication Type Obligatoire Description
provider string Oui Nom du réseau social utilisé pour l'authentification. Si l'utilisateur s'authentifie par son nom d'utilisateur et son mot de passe, la revendication a la valeur xsolla.
external_account_id string ID de l'utilisateur sur votre serveur.
partner_data Données de tout type renvoyées par votre serveur dans le corps de la réponse lors de l'authentification.

Authentification via les réseaux sociaux

Revendications contenues dans le jeton après l'authentification via un réseau social. La présence de ces revendications ne dépend pas de la base de données des utilisateurs.

Revendication Type Obligatoire Description
provider string Oui Nom du réseau social utilisé pour l'authentification.
id string Oui ID utilisateur dans un réseau social.
is_cross_auth boolean Indique que la requête d'authentification silencieuse est en cours.
social_access_token string Paramètre access_token du compte de réseau social utilisé pour l'authentification. Contactez votre gestionnaire de compte pour configurer cette fonctionnalité.
picture string (URL) Lien vers la photo de profil de l'utilisateur dans un réseau social.
birthday date (RFC3339) Date de naissance de l'utilisateur dans un réseau social.
gender string Genre de l'utilisateur dans un réseau social.
name string Pseudo de l'utilisateur dans un réseau social.

Authentification via le protocole OAuth 2.0

Revendications contenues dans le jeton après l'authentification OAuth 2.0.

Revendication Type Obligatoire Description
jti string Oui ID unique du jeton.

Authentification par numéro de téléphone

Revendication contenue dans le jeton après l'authentification par numéro de téléphone.

Revendication Type Obligatoire Description
phone_number string Oui Numéro de téléphone de l'utilisateur utilisé pour l'authentification. Le format du numéro se compose de l'indicatif du pays, de l'indicatif régional et du numéro de ligne, sans aucun séparateur.

JWT serveur

Le jeton du serveur est passé dans l'en-tête X-SERVER-AUTHORIZATION.

La charge utile du jeton contient des informations sur les ressources dont le client OAuth 2.0 est propriétaire. Le jeton a accès aux appels avec authentification côté serveur pour ces ressources.

Revendication Type Obligatoire Description
xsolla_login_project_id string (UUID) Oui ID du projet de connexion dont le client OAuth 2.0 est propriétaire.
resources array Oui

Liste des ressources dont le client OAuth 2.0 est propriétaire. Types de ressources possibles :

  • publisher_id — ressources du commerçant propriétaire du projet de connexion ;
  • publisher_project_id — ressources du projet dans le Compte éditeur.

Chaque groupe est écrit dans le format suivant :

  • name — type de ressource ;
  • value — ID de la ressource.

jti string Oui ID unique du jeton.

Validation du JWT

Après une authentification réussie, un JWT est généré pour chaque utilisateur. Ce JWT est signé à l'aide d'une clé secrète. Afin de garantir la pertinence du JWT et de vérifier qu'il appartient à l'utilisateur de votre projet de connexion, vous devez valider sa valeur.

Pour valider un JWT :

  1. Ouvrez votre projet dans le Compte éditeur et accédez à la section Login.
  2. Dans le panneau d'un projet de connexion, cliquez sur Configure.
  3. Sur la page de navigation, accédez au bloc Security et sélectionnez la section JWT Signature.
  4. Sélectionnez votre méthode de cryptage et copiez la valeur du champ Secret key ou New public JSON Web Key, en fonction de la méthode sélectionnée.
  5. Choisissez la bibliothèque et connectez-la côté serveur de votre application.
  6. Passez la valeur, copiée à l'étape 4, à l'entrée de la fonction de validation.

Remarque

Ne révélez votre clé secrète à personne. Si elle a été compromise, mettez-la à jour.

Erreurs

En cas d'erreur, le serveur Xsolla Login renvoie un objet JSON contenant les champs suivants :

Champ Type Description
code string Code d'erreur du serveur Xsolla Login.
description string Description de l'erreur. Le texte est toujours en anglais. N'utilisez pas ce texte en cas d'erreur, car la valeur peut changer à l'avenir.
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

400 Bad Request

Code Description
0 La requête comporte des paramètres non valides.
010-019 L'authentification du client a échoué (par exemple, client inconnu, authentification client non incluse, ou méthode d'authentification non prise en charge).
010-022 Le statut du paramètre est manquant ou trop faible, car il comporte moins de 8 caractères.
010-023 Le jeton d'autorisation ou d'actualisation n'est pas valide, a expiré, a été révoqué, ne correspond pas à l'URI de redirection utilisé dans la requête d'autorisation ou a été émis pour un autre client.

401 Unauthorized

Code Description
002-016 Jeton non valide.
002-040 Impossible d'autoriser un utilisateur interdit.
003-001 Nom d'utilisateur ou mot de passe incorrect.
003-007 Compte utilisateur non confirmé.
003-025 Une erreur s'est produite lors de l'obtention du jeton d'accès OAuth 2.0.
003-040 Utilisateur non autorisé.
010-026 Le serveur Xsolla Login ou le propriétaire de la ressource a refusé la requête.

403 Forbidden

Code Description
1901-0001 Jeton non valide.

404 Not Found

Code Description
003-002 Utilisateur non trouvé.
003-019 Projet non trouvé.
003-061 Objet non trouvé.

418 I’m a teapot

Code Description
004-001 Une erreur s'est produite.

422 Unprocessable Entity

Code Description
0 Pseudo manquant dans la requête.
002-050 Les paramètres d'authentification à deux facteurs de l'utilisateur n'ont pas été modifiés.
003-003 L'utilisateur avec le nom d'utilisateur spécifié existe déjà.
003-020 Appel non disponible pour ce projet de connexion.
003-022 Ce projet de connexion est mal configuré. Modifiez les paramètres du projet de connexion dans le Compte éditeur Xsolla ou contactez votre responsable de compte.
003-033 Type de projet non conforme.
006-003 Les clients OAuth 2.0 avec client_credentials comme valeur de paramètre grant type ne peuvent avoir qu'une liste d'accès.
010-015 Échec d'authentification du réseau social : SERVICE_NAME.
010-016 Ce compte de réseau social est déjà lié à un autre utilisateur.
010-032 L'authentification via ce réseau social n'est pas activée pour ce projet de connexion. Activez-la dans votre Compte éditeur Xsolla sous la section > Login > votre projet de connexion> Social connections.
030-024 La réinitialisation du mot de passe est désactivée pour ce projet de connexion.
2002-0001 Attributs en double.

429 Too Many Requests

Code Description
002-054 Nombre de tentatives de recherche autorisé dépassé. Attendre une seconde avant la prochaine requête.
010-005 Nombre de requêtes autorisé dépassé.
1900-0001 Nombre de requêtes autorisé dépassé.