Passwordless Authorization

This guide explains how to enable player authorization through your Game App, allowing seamless access to the game hub without requiring players to manually enter their user ID.

Prerequisites

An active Server-to-Server (S2S) API key for request authentication.

Step 1: Intercept the Authorization Deep Link in the Game Client

When the player clicks the login button, the game hub will redirect them to the game deep link. The URL will resemble the following format:

mygame://authorize-player?nonce={nonce}

Here, {nonce} is a unique string generated by the game hub for each authorization request.

The Game Client must intercept the deep link and extract the nonce parameter from the URL. This nonce will be used in the authorization request to the Game Backend.

Step 2: Forward the Authorization Request to the Game Backend

After the player initiates an authorized session, the Game Client should send an authorization request to the Game Backend.

Step 3: Send the Authorization Request to Aghanim

Upon receiving the request from the Game Client, the Game Backend must send a POST request to the Aghanim API using the endpoint Authorize User. Include the following parameters in the request:

Parameter	Description	Required?
`player_id`	The unique identifier for the player to be authorized.	Yes
`nonce`	The unique string provided by the game hub.	Yes
`redirect_path`	The game hub page to redirect the player to.	No
`player_info`	Optional player profile to seed on first authorization. Accepts `name`, `avatar_url`, `attributes`, and `custom_attributes`.	No

Example Request

curl --request POST \
  --url https://api.aghanim.com/s2s/v1/users/authorize \
  --header 'Authorization: Bearer YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "player_id": "2D2R-OP3C",
    "nonce": "N2Q3Y2MGI6bQ",
    "player_info": {
      "name": "Han Solo",
      "avatar_url": "https://example.com/han.png",
      "attributes": { "hard_currency_amount": 500 },
      "custom_attributes": { "faction": "rebel" }
    }
  }'

Example Response

{
  "authorization_url": "https://your-game-hub/go/login?token=dXNyX...FTV0xqTWg&nonce=N2Q3Y2MGI6bQ"
}

Step 4: Redirect the Player to the Authorization URL

Once the Game Backend receives the authorization_url from Aghanim, it should pass this URL back to the Game Client. The Game Client should then launch the default browser and open the authorization URL. This action completes the player’s authorization on the game hub.

Handling Authorization Failures

The game cannot always authorize a player. For example, the player has not yet reached the level required to access the game hub, or the account is restricted. In these cases, tell Aghanim that the login cannot proceed so the player is not left waiting on a loading spinner.

Reject the Authorization Request

When the Game Backend decides that the login cannot proceed, send a POST request to the Aghanim API using the endpoint Reject Authorization. Include the same nonce you received in the authorization deep link:

Parameter	Description	Required?
`nonce`	The unique string provided by the game hub, taken from the authorization deep link.	Yes
`reason`	The reason the authorization cannot proceed. One of `not_eligible` (the player does not meet the requirements to access the hub), `banned`, or `rejected` (generic).	Yes

Example Request

curl --request POST \
  --url https://api.aghanim.com/s2s/v1/users/authorize/reject \
  --header 'Authorization: Bearer YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "nonce": "N2Q3Y2MGI6bQ",
    "reason": "not_eligible"
  }'

Example Response

{
  "error_url": "https://your-game-hub/error?message_code=auth_via_game.not_eligible"
}

Show the Error to the Player

How you surface the failure is up to the game:

In the game client. If you display the error in the game's own UI, no further action is required. You can ignore error_url.
On the game hub. If you prefer to show the error in the browser, pass the error_url back to the Game Client and open it in the default browser, exactly as you would the authorization_url on success. The game hub then displays the corresponding error message to the player.

Need help?
Contact our integration team at integration@aghanim.com