Connecting OAuth authorization

The OAuth 2 protocol is designed to give one service (the partner game) access rights to the user’s resource on another service (games.mail.ru). There is no need to create or store additional passwords. Read more about the protocol in RFC 6749.

Getting the authorization_code

Obtaining an OAuth authorization begins with sending the client’s browser to the following address:

https://games.mail.ru/app/[GMRID]/oauth/authorize?redirect_uri=https%3A%2F%2Fexample.com%2Frand&response_type=code
  • [GMRID] - application ID, part of PATH in the URL
  • response_type - the value of this parameter must be "code"
  • redirect_uri - the address to which the user will be sent in the case of success or failure in authorization. It is recommended you add a random component to redirect_uri.

If authorization is successful and the partner project is successfully accessed, the user should be sent to the following URL:

https://example.com/rand?code=ohxai0joh1shif8oNiengix3phahSaem

In the case of failure, the client will return the following error:

https://example.com/rand?error=invalid_request
https://example.com/rand?error=unauthorized_client
https://example.com/rand?error=access_denied

Read more about these errors in RFC 6749.

Swapping authorization_code for access_token

After an authorization code is received from the client, it must be swapped for a couple of access and refresh tokens. To do this, you must make a server-server API request.

POST /app/[GMRID]/oauth/token HTTP/1.1
Host: games.mail.ru
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_secret=gX1fBat3bV&
code=ohxai0joh1shif8oNiengix3phahSaem&
redirect_uri=https%3A%2F%2Fexample.com%2Frand
  • [GMRID] - application ID, part of PATH in the URL
  • grant_type - the value of the parameter must be "authorization_code"
  • code - an authorization code received from the client
  • client_secret - partner’s secret. The partner can find this in the developer dashboard, on the game’s page, on the "System properties" tab. The applicable field is named "Secret for api.games.mail.ru".
  • redirect_uri - the precise address that was sent in the redirect_uri parameter for obtaining the authorization code with the client

In the case of success, the following response will be sent:

{
    "access_token":"ohxai0joh1shif8oNiengix3phahSaem",
    "token_type":"bearer",
    "expires_in":2592000,
    "refresh_token":"iet1AiSheatiemahzie4eehidahbohgh",
}

After the time indicated in the expires_in parameter, access_token will be deactivated and further operation will require it to be updated.

Updating access_token

POST /app/[GMRID]/oauth/token HTTP/1.1
Host: games.mail.ru
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=iet1AiSheatiemahzie4eehidahbohgh
  • [GMRID] - application ID, part of PATH in the URL
  • grant_type - the value of the parameter must be "refresh_token"
  • refresh_token - the token received when exchanging "code" for "access_token"

In the case of success, the following response will be sent:

{
    "access_token":"ohkohng1Aethielahr0niwai8oonguu3",
    "token_type":"bearer",
    "expires_in":2592000,
    "refresh_token":"iet1AiSheatiemahzie4eehidahbohgh",
}

Obtaining user information based on access_token

GET /app/[GMRID]/oauth/info?access_token=ohkohng1Aethielahr0niwai8oonguu3 HTTP/1.1
Host: games.mail.ru
  • [GMRID] - application ID, part of PATH in the URL
  • access_token - the token received when swapping "code" for "access_token"

In the case of success, the following response will be sent:

{
    "status": "ok",
    "uid": "1252352"
}