Xsolla-logo

Visão geral

Esta seção descreve as chamadas de API para trabalhar com Login. Configure seu projeto Login na Conta de Distribuidor antes de enviar solicitações.

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

Baixar definição de API

Você pode baixar a definição de API em dois formatos:

Glossário

Você tem acesso aos seguintes tipos de projeto Login na Conta de Distribuidor:

  • Projeto Login padrão
  • Projeto Shadow Login

Para obter mais informações sobre ele, consulte o recurso Conta multiplataforma.

Limites de taxa

São as restrições aplicadas pela API Xsolla sobre a frequência de acesso por um usuário dentro de um período de tempo definido.

Projeto Login padrão

É um projeto Login usado para armazenar contas principais.

Projeto Shadow Login

É um projeto Login usado para armazenar contas de plataforma.

Conta principal

É um tipo de conta criado em um projeto Login padrão e vinculado a contas de plataforma. A conta principal é usada para identificar o jogador em diferentes plataformas.

Conta da plataforma

É um tipo de conta criado em um projeto de Login sombra e conectado a uma plataforma de distribuição definida. A conta da plataforma não pode ser vinculada a outra conta da plataforma. Além disso, não é possível desvincular as contas de uma conta principal.

Plataforma de publicação

É uma plataforma de jogos que é usada para a distribuição de jogos (por exemplo, Steam, PlayStation, Xbox, etc.).

Autenticação

A Login API oferece suporte aos seguintes tipos de token:

Authentication schemes

Você pode determinar se uma chamada de API ocorre no lado do cliente ou do servidor pelo esquema de autenticação:

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

Obtenção de um token de usuário

Para obter o token, envie uma das seguintes solicitações:

Após a autenticação JWT, o usuário é redirecionado para o URL de retorno de chamada com um token em um parâmetro de consulta: <Callback URL>?token=<User token (JWT)>.

Após a autenticação baseada no protocolo OAuth 2.0, envie a solicitação Generate JWT ao servidor do Xsolla Login para trocar o parâmetro code recebido por um token de usuário (access_token).

Obtenção de um token de servidor

Para obter um token de servidor:

  1. Configure o cliente OAuth 2.0 do servidor.
  2. Gere o JWT do servidor.

Configure o cliente OAuth 2.0 do servidor

  1. Abra seu projeto na Conta de Distribuidor e vá para a seção Login.
  2. Clique em Configure no painel de um projeto Login.
  3. Vá para o bloco Security e selecione a seção OAuth 2.0.
  4. Clique em Adicionar cliente OAuth 2.0.
  5. Marque a caixa Server (server-to-server connection).
  6. Especifique o Tempo de vida do token.
  7. Clique em Connect.
  8. Copie e salve o ID do cliente e a chave secreta.

Geração do JWT do servidor

No back-end do seu aplicativo, implemente um método para obter o JWT do servidor usando a chamada Generate JWT API. A solicitação deve conter os seguintes parâmetros:

  • grant_type é o tipo de obtenção de JWT; passa o valor client_credentials.
  • client_secret é a chave secreta que é recebida quando você configura o cliente OAuth 2.0 do servidor.
  • client_id é o ID do cliente recebido quando você configura o cliente OAuth 2.0 do servidor.

Limites de taxa

Para evitar sobrecarregar o sistema Xsolla e proteger contra picos repentinos no tráfego de entrada, a Xsolla limita o número de solicitações recebidas pela API Xsolla dentro de um período de tempo especificado. Se o limite for excedido, a API Xsolla retornará uma resposta HTTP com o código de status 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

Os limites de taxa para métodos do lado do cliente não mudam e são necessários para evitar ataques de força bruta. A taxa máxima de solicitação para métodos do lado do servidor é maior do que para métodos do lado do cliente. Você pode consultar as recomendações sobre como gerenciar limites de taxa na documentação.

Observação Em certos casos, é possível ajustar os limites de taxa por solicitação. Para solicitar o ajuste dos limites tarifários, entre em contato com o Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.

Estrutura JWT

Cada token tem um formato JWT e contém uma informação definida em uma carga.

JWT do usuário

O JWT do usuário é um token recebido como resultado da autenticação ou cadastro. Uma carga de token contém informações sobre o usuário e a chamada de autenticação.

Para obter um token de usuário por meio do protocolo OAuth 2.0, você precisa de um cliente OAuth 2.0. O token de usuário é passado no cabeçalho Authorization: Bearer <JWT>.

Principais reivindicações

Um token conterá as principais declarações após a autenticação ou confirmação do endereço de e-mail. A presença dessas declarações não depende do banco de dados do usuário e da chamada de autenticação.

 
Reivindicar Tipo Obrigatório Descrição
exp Carimbo de data/hora Unix Sim Data e hora da expiração do token. O tempo de expiração padrão é de 24 horas. Você pode alterar o tempo de expiração para cada projeto Login.
iss cadeia de caracteres Sim Serviço que assinou o token: https://login.xsolla.com.
iat Carimbo de data/hora Unix Sim Data e hora de entrega do token.
sub cadeia de caracteres (UUID) Sim ID do usuário escrito no lado do servidor Xsolla Login.
groups matriz Sim

A lista de grupos em que o usuário está. Cada grupo é escrito no seguinte formato:

  • id — ID do grupo
  • name — nome do grupo
  • is_default — exibe se o grupo é padrão ou não (true ou valores false).

Só pode haver um grupo padrão. Esse grupo inicialmente inclui todos os usuários antes que eles sejam distribuídos em grupos diferentes.

xsolla_login_project_id cadeia de caracteres (UUID) Sim ID do projeto Login.
type cadeia de caracteres

Opção de autenticação:

  • xsolla_login — login via nome de usuário/e-mail e senha.
  • social — login social.
  • email — login sem senha por meio de um código único recebido por e-mail.
  • phone — login sem senha por meio de um código único recebido por SMS.
  • firebase — login via nome de usuário/e-mail e senha quando o sistema de armazenamento de dados do usuário for o Firebase.
  • playfab — login via nome de usuário/e-mail e senha quando o sistema de armazenamento de dados do usuário for o PlayFab.
  • proxy — login via nome de usuário/e-mail e senha quando o armazenamento de dados do usuário for personalizado.
  • device — login com o ID do dispositivo.
  • server_custom_id — login com ID personalizado.

Só pode haver um grupo padrão. Esse grupo inicialmente inclui todos os usuários antes que eles sejam distribuídos em grupos diferentes.

avatar cadeia de caracteres URL do avatar do usuário.
username cadeia de caracteres Nome de usuário.
publisher_id número inteiro ID de um comerciante que possui um projeto de login.
email cadeia de caracteres Endereço de e-mail do usuário.
payload cadeia de caracteres Informações adicionais que são passadas no parâmetro de carga durante a autenticação.
promo_email_agreement valor booleano

Pode ter um dos seguintes valores:

  • true se o usuário concordar em receber uma newsletter.
  • false caso contrário.
Tem o valor true por padrão.

Para adicionar o recurso ao formulário de registro do Login widget:

  • Contate seu Gerente da Conta se você utiliza o Widget 2.0.
  • Adicione o parâmetro fields com o valor promo_email_agreement ao código de inicialização se você utiliza a versão anterior do widget.

connection_information cadeia de caracteres Mostra se o usuário confirmou a data de nascimento ou não. A confirmação é feita através do serviço okname.

Armazenamento PlayFab

Declarações contidas no token após a autenticação se você usar o armazenamento PlayFab.

Reivindicar Tipo Obrigatório Descrição
external_account_id cadeia de caracteres Sim ID do usuário PlayFab.
session_ticket cadeia de caracteres Sim

Um parâmetro SessionTicket recebido durante uma solicitação de autenticação ou solicitações para a PlayFab API.

Um token conterá a declaração se você autenticar usuários por meio do protocolo OAuth 2.0 e passar o valor playfab para o parâmetro scope.

entity_token cadeia de caracteres Sim Um parâmetro EntityToken.EntityToken.
entity_type cadeia de caracteres Sim Um parâmetro EntityToken.Entity.Type. Só aceita o valor title_player_account.
entity_id cadeia de caracteres Sim Um parâmetro EntityToken.Entity.Id.

Armazenamento personalizado

Declarações contidas no token após a autenticação se você usar armazenamento personalizado.

Reivindicar Tipo Obrigatório Descrição
provider cadeia de caracteres Sim Nome de uma rede social usada para autenticação. Se o usuário autenticar via nome de usuário e senha, a declaração terá o valor xsolla.
external_account_id cadeia de caracteres ID do usuário no lado do servidor.
partner_data Dados de qualquer tipo retornados pelo servidor no corpo da resposta durante a autenticação.

Autenticação social

Declarações que estão contidas no token após a autenticação por meio de uma rede social. A presença dessas declarações não depende do banco de dados do usuário.

Reivindicar Tipo Obrigatório Descrição
provider cadeia de caracteres Sim Nome de uma rede social usada para autenticação.
id cadeia de caracteres Sim ID de usuário em uma rede social.
is_cross_auth valor booleano Mostra que a solicitação de autenticação silenciosa está em andamento.
social_access_token cadeia de caracteres Parâmetro access_token de conta de rede social usado para autenticação. Entre em contato com seu Gerente de Conta para configurar o recurso.
picture cadeia de caracteres (URL) Link para a foto de perfil do usuário em uma rede social.
birthday data (RFC3339) Data de nascimento do usuário em uma rede social.
gender cadeia de caracteres Gênero do usuário em uma rede social.
name cadeia de caracteres Apelido do usuário em uma rede social.

Autenticação através do protocolo OAuth 2.0

Declarações contidas no token após a autenticação do OAuth 2.0.

Reivindicar Tipo Obrigatório Descrição
jti cadeia de caracteres Sim ID de token exclusivo.

Autenticação através de um número de telefone

Reivindicação que está contida no token após a autenticação por meio de um número de telefone.

Reivindicar Tipo Obrigatório Descrição
phone_number cadeia de caracteres Sim Número de telefone do usuário usado para autenticação. O formato de número de telefone com base no código do país, código de área e número de linha sem divisórias.

Servidor JWT

O token do servidor é passado no cabeçalho X-SERVER-AUTHORIZATION.

A carga do token contém informações sobre recursos pertencentes ao cliente OAuth 2.0. O token tem acesso a chamadas com autenticação baseada em servidor para esses recursos.

Reivindicar Tipo Obrigatório Descrição
xsolla_login_project_id cadeia de caracteres (UUID) Sim ID de um projeto Login que possui o cliente OAuth 2.0.
resources matriz Sim

Lista de recursos pertencentes a um cliente OAuth 2.0. Tipos possíveis de recursos:

  • publisher_id — recursos de um comerciante proprietário do projeto Login
  • publisher_project_id — ecursos de um projeto na Conta de Distribuidor.

Cada grupo é escrito no seguinte formato:

  • name — tipo de recurso
  • value — ID do recurso

jti cadeia de caracteres Sim ID de token exclusivo.

Validação JWT

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

Aviso

Não revele sua chave secreta a ninguém. Se ela foi comprometida, atualize-a.

Erros

Em caso de respostas de erro, o servidor do Xsolla Login retorna um objeto JSON com os seguintes campos:

Campo Tipo Descrição
código cadeia de caracteres Código de erro do servidor Xsolla Login.
descrição cadeia de caracteres Descrição do erro. O texto está sempre em inglês. Não use este texto em caso de erro, pois o valor pode mudar no futuro.
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

400 Solicitação incorreta

Código Descrição
0 A solicitação tem parâmetros inválidos.
010-019 Falha na autenticação do cliente (por exemplo: cliente desconhecido, nenhuma autenticação de cliente incluída, ou método de autenticação não suportado).
010-022 Estado do parâmetro ausente ou muito fraco, pois tem menos de 8 caracteres.
010-023 O token de concessão ou atualização de autorização é inválido, expirou, foi revogado, não corresponde ao URL de redirecionamento usado na solicitação de autorização, ou foi emitido para outro cliente.

401 Não autorizado

Código Descrição
002-016 Token inválido.
002-040 Não foi possível autorizar o usuário banido.
003-001 Nome de usuário ou senha errados.
003-007 Conta de usuário não confirmada.
003-025 Ocorreu um erro ao obter o token de acesso OAuth 2.0.
003-040 Usuário não autorizado.
010-026 Solicitação negada ao servidor Xsolla Login ou proprietário do recurso.

403 Proibido

Código Descrição
1901-0001 Token inválido.

404 Não encontrado

Código Descrição
003-002 Usuário não encontrado.
003-019 Projeto não encontrado.
003-061 Objeto não encontrado.

418 Eu sou um bule

Código Descrição
004-001 Ocorreu um erro.

422 Entidade não processável

Código Descrição
0 Apelido perdido na consulta.
002-050 As configurações de autenticação de dois fatores do usuário não foram alteradas.
003-003 Já existe um usuário com esse nome de usuário especificado.
003-020 Chamada indisponível para este projeto Login.
003-022 Este projeto Login foi configurado incorretamente. Altere as configurações deste projeto Login na Conta de Distribuidor Xsolla ou entre em contato com seu Gerente de Conta.
003-033 Tipo de projeto incompatível.
006-003 Clientes OAuth 2.0 com o tipo de concessão client_credentials somente podem ter listas de acesso.
010-015 Falha na autenticação de rede social: SERVICE_NAME.
010-016 Essa conta social já está vinculada a outro usuário.
010-032 Autenticação através desta rede social não habilitada para este projeto Login. Habilite-o em sua Conta de Distribuidor Xsolla > Login > Seu projeto Login > Conexões sociais.
030-024 Redefinição de senha desabilitada para este projeto Login.
2002-0001 Atributos duplicados.

429 Pedidos Demais

Código Descrição
002-054 O número permitido de tentativas de pesquisa excedeu. Aguarde um segundo antes da próxima solicitação.
010-005 Número permitido de solicitações excedido.
1900-0001 Número permitido de solicitações excedido.