Xsolla-logo

Überblick

Dieser Abschnitt beschreibt API-Aufrufe für die Arbeit mit Login. Konfigurieren Sie Ihr Login-Projekt im Kundenportal, bevor Sie Anfragen senden.

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

API-Definition herunterladen

Die API-Definition steht in zwei Formaten zum Download bereit:

Begriffserläuterung

Im Kundenportal haben Sie Zugriff auf die folgenden Login-Projekttypen:

  • Standard-Login-Projekt
  • Schatten-Login-Projekt

Weitere Informationen dazu finden Sie unter Plattformübergreifendes Konto.

Ratenbegrenzungen

Are the restrictions applied by Xsolla API on the frequency of access by a user within a defined timeframe.

Standard-Login-Projekt

Ist ein Login-Projekt, das zum Speichern von Hauptkonten verwendet wird.

Schatten-Login-Projekt

Ist ein Login-Projekt, das zum Speichern von Plattformkonten verwendet wird.

Hauptkonto

Ist ein in einem Standard-Login-Projekt erstellter Kontotyp und wird mit Plattformkonten verknüpft. Das Hauptkonto dient dazu, Spieler auf verschiedenen Plattformen zu identifizieren.

Plattformkonto

Ist ein in einem Schatten-Login-Projekt erstellter Kontotyp und wird mit einer bestimmten Publishing-Plattform verknüpft. Das Plattformkonto lässt sich mit keinem weiteren Plattformkonto verknüpfen. Zudem können Sie die Verknüpfung zwischen einem solchen Konto und einem Hauptkonto nicht aufheben.

Publishing-Plattform

Ist eine Plattform zur Distribution von Spielen (z. B. Steam, PlayStation, Xbox usw.).

Authentifizierung

Die Login API unterstützt die folgenden Tokentypen:

Authentication schemes

Ob ein API-Aufruf client- oder serverseitig erfolgt, können Sie anhand des Authentifizierungsschemas feststellen:

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

Benutzertoken abrufen

Senden Sie eine der folgenden Anfragen, um den Token abzurufen:

Nach der JWT-Authentifizierung wird der Benutzer mithilfe eines Tokens in einem Abfrageparameter zur Rückruf-URL weitergeleitet: <Callback URL>?token=<User token (JWT)>.

Senden Sie nach der auf dem OAuth 2.0-Protokoll basierenden Authentifizierung die Anfrage JWT generieren an den Xsolla-Login-Server, um den empfangenen code-Parameter gegen einen Benutzertoken (access_token) zu tauschen.

Servertoken abrufen

So rufen Sie ein Servertoken ab:

  1. Richten Sie den OAuth 2.0-Serverclient ein.
  2. Generieren Sie den JWT.

OAuth 2.0-Serverclient einrichten

  1. Öffnen Sie Ihr Projekt im Kundenportal, und wechseln Sie zum Abschnitt Login.
  2. Klicken Sie beim gewünschten Login-Projekt auf Konfigurieren.
  3. Scrollen Sie zum Block Sicherheit, und wählen Sie OAuth 2.0 aus.
  4. Click Add OAuth 2.0 Client.
  5. Aktivieren Sie das Kontrollkästchen Server (Server-zu-Server-Verbindung).
  6. Legen Sie die Tokenlebensdauer fest.
  7. Klicken Sie auf Verknüpfen.
  8. Kopieren und speichern Sie die Client-ID und den geheimen Schlüssel.

Server-JWT generieren

Implementieren Sie im Backend Ihrer Anwendung eine Methode, um den Server-JWT mithilfe des API-Aufrufs JWT generieren abzurufen. Die Anfrage muss folgende Parameter enthalten:

  • grant_type is the type of getting JWT, pass the client_credentials value.
  • client_secret is the secret key that is received when you set up the server OAuth 2.0 client.
  • client_id is the client ID received when you set up the server OAuth 2.0 client.

Ratenbegrenzungen

To prevent Xsolla system overloads and protect against sudden spikes in incoming traffic, Xsolla limits the number of requests received by the Xsolla API within a specified period of time. If the limit is exceeded, the Xsolla API returns an HTTP response with the 429 status code.

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

Rate limits for client-side methods do not change and are necessary to prevent brute-force attacks. The maximum request rate for server-side methods is higher than for client-side methods. You can refer to the recommendations on how to manage rate limits in the documentation.

Note In certain cases, it is possible to adjust the rate limits by request. To request the rate limits adjustment, contact your Customer Success Manager or email csm@xsolla.com.

JWT-Struktur

Jeder Token hat ein JWT-Format und enthält eine bestimmte Information in einer Payload.

Benutzer-JWT

Ein Benutzer-JWT ist ein Token, der infolge einer Authentifizierung oder Registrierung empfangen wird. Eine Token-Payload enthält Informationen über den Benutzer und den Authentifizierungsaufruf.

Um einen Benutzertoken über das OAuth 2.0-Protokoll abzurufen, ist ein OAuth  2.0-Client erforderlich. Der Benutzertoken wird im Header Authorization: Bearer <JWT> übermittelt.

Wichtige Claims

Nach der Authentifizierung oder Bestätigung der E-Mail-Adresse enthält ein Token die wichtigsten Claims. Ob diese Claims vorhanden sind, hängt nicht von der Nutzerdatenbank und dem Authentifizierungsaufruf ab.

 
Claim Typ Erforderlich Beschreibung
exp Unix-Zeitstempel Ja Datum und Uhrzeit des Tokenverfalls. Die Standardverfallszeit beträgt 24 Stunden. Sie können die Verfallszeit für jedes Login-Projekt individuell festlegen.
iss String Ja Dienst, der den Token signiert hat: https://login.xsolla.com.
iat Unix-Zeitstempel Ja Datum und Uhrzeit der Tokenübermittlung.
sub String (UUID) Ja Aufseiten des Xsolla-Login-Servers geschriebene Benutzer-ID.
groups Array Ja

Liste der Gruppen, denen der Benutzer zugeordnet ist. Jede Gruppe wird in dem folgendem Format geschrieben:

  • id – Gruppen-ID
  • name – Gruppenname
  • is_default – ob es sich um eine Standardgruppe handelt oder nicht (true oder false).

Es kann nur eine Standardgruppe geben. Diese Gruppe umfasst zunächst alle Benutzer, bevor diese verschiedenen Gruppen zugeordnet werden.

xsolla_login_project_id String (UUID) Ja Login-Projekt-ID.
type String

Authentifizierungsoption:

  • xsolla_login – Anmeldung über Benutzername/E-Mail-Adresse und Passwort
  • social – Anmeldung über soziale Netzwerke
  • email – passwortlose Anmeldung über einen per E-Mail erhaltenen Einmalcode.
  • phone – passwortlose Anmeldung über einen per SMS erhaltenen Einmalcode.
  • firebase – Anmeldung über Benutzername/E-Mail-Adresse und Passwort, wenn die Nutzerdaten bei Firebase gespeichert sind.
  • playfab – Anmeldung über Benutzername/E-Mail-Adresse und Passwort, wenn die Nutzerdaten bei PlayFab gespeichert sind.
  • proxy — Anmeldung über Benutzername/E-Mail-Adresse und Passwort, wenn die Nutzerdaten im eigenen Speicher gespeichert sind.
  • device – Anmeldung mit Geräte-ID.
  • server_custom_id – Anmeldung mit selbst definierter ID.

Es kann nur eine Standardgruppe geben. Diese Gruppe umfasst zunächst alle Benutzer, bevor diese verschiedenen Gruppen zugeordnet werden.

avatar String Benutzer-Avatar-URL.
username String Benutzername.
publisher_id Integer ID eines Händlers, dem ein Login-Projekt gehört.
email String E-Mail-Adresse des Benutzers.
payload String Zusätzliche Informationen, die während der Authentifizierung im Payload-Parameter übermittelt werden.
promo_email_agreement boolesch

Folgende Werte sind möglich:

  • true, wenn der Benutzer dem Erhalt eines Newsletters zustimmt.
  • andernfalls false.
true ist standardmäßig eingestellt.

So fügen Sie die Funktion der Registrierungsmaske des Login-Widgets hinzu:

  • Wenden Sie sich an Ihren Account Manager, wenn Sie das Widget 2.0 verwenden.
  • Fügen Sie den Parameter fields mit dem Wert promo_email_agreement in den Initialisierungscode ein, wenn Sie eine vorherige Version des Widgets verwenden.

connection_information String Zeigt an, ob der Benutzer sein Geburtsdatum bestätigt hat oder nicht. Die Bestätigung erfolgt über den Dienst okname.

PlayFab-Speicher

Claims, die nach der Authentifizierung im Token enthalten sind, sofern Sie den PlayFab-Speicher verwenden.

Claim Typ Erforderlich Beschreibung
external_account_id String Ja PlayFab-ID des Benutzers.
session_ticket String Ja

Ein während einer Authentifizierungsanfrage oder während Anfragen an die PlayFab API empfangener SessionTicket-Parameter.

Ein Token enthält diesen Claim, wenn Sie Benutzer über das OAuth 2.0-Protokoll authentifizieren und dabei den Wert playfab an den Parameter scope übermitteln.

entity_token String Ja Ein EntityToken.EntityToken-Parameter.
entity_type String Ja Ein EntityToken.Entity.Type-Parameter. Einzig möglicher Wert:title_player_account.
entity_id String Ja Ein EntityToken.Entity.Id-Parameter.

Eigener Speicher

Claims, die nach der Authentifizierung im Token enthalten sind, sofern Sie einen eigenen Speicher verwenden.

Claim Typ Erforderlich Beschreibung
provider String Ja Name des sozialen Netzwerks, das zur Authentifizierung verwendet wird. Wenn sich der Benutzer über einen Benutzernamen und ein Passwort authentifiziert, hat der Claim den Wert xsolla.
external_account_id String Benutzer-ID aufseiten Ihres Servers.
partner_data Data of any type returned by your server in the response body during authentication. To enable the transmission of this claim, contact your Customer Success Manager or email to csm@xsolla.com
social_access_token Access token of the social network through which the user was authenticated. To enable the transmission of this claim, contact your Customer Success Manager or email to csm@xsolla.com.

Authentifizierung über soziale Netzwerke

Claims, die nach der Authentifizierung über ein soziales Netzwerk im Token enthalten sind. Ob diese Claims vorhanden sind, hängt nicht von der Nutzerdatenbank ab.

Claim Typ Erforderlich Beschreibung
provider String Ja Name des zur Authentifizierung verwendeten sozialen Netzwerks.
id String Ja Benutzer-ID im sozialen Netzwerk.
is_cross_auth boolesch Zeigt an, dass die Stille-Authentifizierung-Anfrage läuft.
social_access_token String Der zur Authentifizierung genutzte access_token-Parameter des Social-Media-Kontos. Wenden Sie sich an Ihren Account Manager, um die Funktion einzurichten.
picture String (URL) Link zum Profilbild des Benutzers in einem sozialen Netzwerk.
birthday Datum (RFC3339) Geburtsdatum des Benutzers in einem sozialen Netzwerk.
gender String Geschlecht des Benutzers in einem sozialen Netzwerk.
name String Nickname des Benutzers in einem sozialen Netzwerk.

Authentifizierung über das OAuth 2.0-Protokoll

Claims, die nach der OAuth 2.0-Authentifizierung im Token enthalten sind.

Claim Typ Erforderlich Beschreibung
jti String Ja Eindeutige Token-ID.

Authentifizierung über eine Telefonnummer

Claim, der nach der Authentifizierung über eine Telefonnummer im Token enthalten ist.

Claim Typ Erforderlich Beschreibung
phone_number String Ja Die zur Authentifizierung verwendete Telefonnummer des Benutzers. Das Telefonnummernformat setzt sich zusammen aus Landesvorwahl, nationaler Vorwahl und Anschlusskennung ohne Trennzeichen.

Server-JWT

Der Servertoken wird im X-SERVER-AUTHORIZATION-Header übermittelt.

Die Token-Payload enthält Informationen über Ressourcen, die dem OAuth  2.0-Client gehören. Der Token kann auf diese Ressourcen durch Aufrufe mit serverbasierter Authentifizierung zugreifen.

Claim Typ Erforderlich Beschreibung
xsolla_login_project_id String (UUID) Ja ID eines Login-Projekts, das dem OAuth 2.0-Client gehört.
resources Array Ja

Liste der Ressourcen, die einem OAuth 2.0-Client gehören. Mögliche Ressourcentypen:

  • publisher_id – Ressourcen eines Händlers, dem das Login-Projekts gehört
  • publisher_project_id – Ressourcen eines Projekts im Kundenportal.

Jede Gruppe wird im folgenden Format geschrieben:

  • name – Ressourcentyp
  • value – Ressourcen-ID

jti String Ja Eindeutige Token-ID.

JWT-Validierung

To validate the JWT, use the following Login API calls:

Hinweis

Geben Sie Ihren geheimen Schlüssel niemals weiter. Falls er kompromittiert wurde, aktualisieren Sie ihn bitte.

Fehler

| Error Code | Description | Recommendation | |---------------------------|---------------------------------------------------

---------------------------------------------------------------------------|:---

Fehler

Bei Fehlermeldungen gibt der Xsolla-Login-Server ein JSON-Objekt mit den folgenden Feldern zurück:

Feld Typ Beschreibung
code String Fehlercode des Xsolla-Login-Servers.
Beschreibung String Fehlerbeschreibung. Der Text ist immer in Englisch. Verwenden Sie diesen Text nicht im Falle eines Fehlers, da sich der Wert in Zukunft ändern kann.
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

| Error Code | Description | Recommendation | |---------------------------|---------------------------------------------------


---------------------------------------------------------------------------|:---


---------------------------------------------------------------------------:| | 002-016 | Invalid JWT. | The user should try to log in again. | | 002-027 | Parameter is invalid. | Make sure all request parameters are correct. | | 002-028 | Parameter was not passed. | Make sure all required parameters are provided. | | 002-040 | This user is banned. | The user should contact the game support team. | | 002-043 | This phone number cannot receive SMS. Use a different number. | The user should try another phone number that can receive SMS. | | 002-050 | User MFA settings have not changed. | The error occurs when trying to enable two-factor authentication if it's already enabled, or disable it if it's already disabled. | | 002-056 | Invalid phone number. Verify the number or try another one. | The user should verify the phone number or enter a different one. | | 002-057 | Too many login attempts. | The user should try again later. If you believe this error should not occur, please contact the integrator team in any messenger. | | 002-058 | You exceeded login attempts limit. To unblock your account, follow the link in the email that we sent or reset your password. | The user should use the link in the email to unblock their account or reset the password. | | 002-060 | User younger than required age. | Inform the user of the age restrictions. | | 003-001 | Incorrect email address/username or password. | The user should verify the entered information and try again. | | 003-002 | User is not signed up. | The user should sign up in the game to continue. | | 003-003 | User with this username already exists. Try another username. | The user should try a different username. | | 003-004 | User with this email address already exists. Try another email address. | The user should use a different email address. | | 003-005 | Email address does not exist. Try another email address. | The user should try a different email address. | | 003-007 | Account not activated. Please confirm email address. | The user should confirm their email address to activate the account. If they haven't received a confirmation email, they should check the spam folder. | | 003-008 | Changing email address not allowed. | Changing the email address is not allowed. | | 003-009 | User search request wrong. | The search failed for technical reasons, please try again later. | | 003-010 | Changing birth date is unavailable. | Changing the birth date is not allowed. | | 003-011 | Email address not confirmed. Try another email address or confirm this one. | The user should confirm the email address or use another one that has not been previously used during registration. | | 003-012 | User with specified phone number already exists. | The user should confirm the phone number or use another one that has not been previously used during registration. | | 003-019 | Login with this project ID not found. | Check the existence of the authentication variant with the passed ID. | | 003-020 | Call unavailable for this Login project. | Check the authorization option settings in your Publisher Account. | | 003-021 | Logging in via username/password not allowed. | The user should contact game support. | | 003-022 | Incorrect project configuration. | Verify the authorization option settings in your Publisher Account. | | 003-023 | Signing up via username/password not allowed. | Registration is not allowed for this authorization option. The user should contact game support. | | 003-030 | Link has expired. Please perform password recovery again. | The password reset link has expired or is incorrect. The user should attempt to reset the password again. | | 003-049 | Too many attempts to use confirmation code. Try again later. | The user should try again later. | | 007-001 | Login via phone is currently unavailable in your country. Please try a different login method. | The user should use an alternative login method. | | 008-001 | Passwordless login URL not configured. | Add the correct login URL in the authorization option settings in your Publisher Account (section User database > Storage > Custom storage). | | 008-002 | User verification URL not configured. | Add the correct user verification URL in the authorization option settings in your Publisher Account (section User database > Storage > Custom storage). | | 008-003 | New user URL not configured. | Add the correct URL in the authorization option settings in your Publisher Account (section User database > Storage > Custom storage). | | 008-004 | Password reset URL not configured. | Add the correct password reset URL in the authorization option settings in your Publisher Account (section User database > Storage > Custom storage). | | 008-005 | PlayFab Title ID invalid. | Ensure the correct Title ID is specified in the authorization option settings in your Publisher Account (section User database > Storage). | | 008-006 | PlayFab API key invalid. | Ensure the PlayFab API key is valid. | | 008-008 | Invalid response from your API. It must contain user ID as "accountID" response body parameter. | Ensure the server returns the accountID parameter in the response body. | | 008-009 | Invalid URL in Custom storage settings. | Verify the URLs specified in the Custom storage settings in the authorization option in your Publisher Account (section User database > Storage > Custom storage). | | 008-011 | Set new password page URL not configured. | Ensure that the callback URL for password reset is specified in the authorization option settings in your Publisher Account (section Password settings). | | 008-013 | Consent page URL not configured or invalid. | Ensure that a link to the user agreement is specified in the authorization option settings in your Publisher Account (section Legal Terms

Policies and Agreements). | | 008-014 | Okta integration not completed. | Contact the integration team through any messenger. | | 008-015 | SAML integration not completed. | Contact the integration team through any messenger. | | 008-016 | Firebase API key not set. | Add the API key to the settings in your Publisher Account (section Legal Terms > Policies and Agreements). | | 010-004 | Service temporarily unavailable. Try again later. | The user should try again later. | | 010-005 | Allowable number of requests exceeded. Try again later. | The user should try again later. | | 010-006 | If this social profile is unlinked, no authentication methods will be available. | The user should add another authentication method before unlinking the social network. | | 010-007 | Incorrect CAPTCHA input. Try again. | The user should complete the CAPTCHA again. | | 010-010 | Invalid confirmation code. | The user should verify the code and try again. | | 010-014 | Your code is expired. Return to the login page and log in again. | The user should log in again from the login page. | | 010-015 | Something went wrong during authentication with this social network. Try again later. | The user should try again later. | | 010-016 | This social account is already linked to another user. | The user should use a different social account. If they believe this is an error, they should contact the integration team through any messenger. | | 010-017 | Client authentication failed. Some request parameters are missing in request or have invalid values. | Verify the correctness of the request parameters being sent. | | 010-019 | Client authentication failed. Client with this client_id value does not exist. | Ensure that a client with the provided client_id exists. | | 010-020 | Client authentication failed. Parameter scope is invalid or malformed. | Ensure that the provided scope parameter is correct. Refer to the instructions for detailed setup information. | | 010-021 | Client authentication failed. Parameter response_type is invalid or malformed. You should pass value of code parameter to response_type. | Ensure that the value of the response_type parameter is set to "code". | | 010-022 | Client authentication failed. Parameter state is missing or its value has less than 8 characters. | Ensure that the state parameter is present and consists of at least 8 characters. | | 010-023 | Client authentication failed. Authorization code, authorization grant types, or refresh token are invalid or expired. Also this error is returned when the redirect_uri given in authorization grant type does not match the URI provided in access token request. | Ensure that the authorization code is valid and not expired, and that the redirect_uri parameter contains an authorized URL. Refer to the instructions for detailed setup information. | | 010-026 | The resource owner or authorization server denied the request. | Ensure that you have sufficient permissions to access the resource. | | 010-030 | Cross social network is not enabled for this Login. | Ensure that cross-authentication is enabled for the authorization option. Refer to the instructions for detailed setup information. | | 010-031 | Social provider already exists. | The error occurs when attempting to connect a social network that is already enabled. | | 010-032 | Social network is not enabled for this Login. You can enable it in your Xsolla Publisher Account > Login Project > Social connections. | Ensure that the social network is enabled and configured in the authorization option settings in your Publisher Account (section Authorization via Social Networks). | | 010-033 | This call is temporary unavailable. | The user should try again later. | | 010-035 | Dependency service is unavailable | The user should try again later. | | 010-045 | Account with this social provider email address already exists. | The user should use a different social account for registration. | | 030-024 | Password recovery is not allowed. | The user should contact the game support team. | | 040-001 | Email address must be 254 characters or shorter. | The user should enter an email address containing no more than 254 characters. | | 040-002 | Username of the email address is invalid. Try another email address. | The user should enter a valid email address. | | 040-003 | Local part of the email address is too long. | The user should enter a different email address. | | 040-004 | Email address domain is invalid. Try another email address. | The user should contact Xsolla support. | | 040-005 | Email address should contain one @ character only. (E.g., username@example.com) | The user should enter an email with only one @ character. | | 040-006, 040-007, 040-008 | Email address domain is invalid. Try another email address. | The user should contact Xsolla support. | | 040-009 | Email address domain doesn’t exist. Try another email address. | The user should enter an email with an existing domain. | | 040-010 | Email address domain is not allowed. Try another email address. | The user should contact Xsolla support. | | 010-018 | Email address is invalid. Try another email address. | The user should enter a different email address. | | 300-003 | Allowable number of requests exceeded. Try again later. | The user should try again later. | | 300-005 | Failed to resend code. Try again later. | The user should try again later. | | 300-006 | Incorrect confirmation code. Check the code that you received and try again. | The user should verify and re- enter the confirmation code. | | 300-008 | You've exceeded the maximum number of attempts. Use the new code sent to your email or phone. | The user should use the new code sent to their email or phone. | | 003-007 | User account not confirmed. | The user should confirm their email address to activate the account. If they haven't received a confirmation email, they should check the spam folder. | | 003-025 | Error occurred while getting OAuth 2.0 access token. | The user should try a different authentication method. | | 003-040 | Unauthorized user. | The user should log in again. | | 003-033 | Mismatch project type. | Ensure that shadow authentication is used for the authorization option. | | 2002-0001 | Duplicated attributes. | Make sure that the attribute being created has not been previously added to the user. |