Skip to main content

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.

Webhook general flow image
Webhook general flow image

Prerequisites

  • An active Server-to-Server (S2S) API key for request authentication.
  • A Deep Link URL configured in the Aghanim Dashboard under Customization → Login (see below).

The Deep Link URL is the address the game hub opens when the player taps the login button. Set it in the Aghanim Dashboard under Customization → Login → Deep Link URL.

This is the reverse of game → hub deep links: there your game opens a link into the hub (/go/login?player_id=…); here the hub opens a link into your game to authorize the player.

The game hub appends the nonce to this URL as a query parameter automatically — you do not need to add a {nonce} placeholder yourself. For example, a configured value of https://your-game-server.com/authorize-player becomes https://your-game-server.com/authorize-player?nonce=<value> when the hub opens it. Any static query parameters you include in the configured URL are preserved.

Prefer an https App Link / Universal Link over a custom scheme

Use an https:// Android App Link / iOS Universal Link that your own domain handles (for example https://your-game-server.com/authorize-player) rather than a custom scheme such as mygame://authorize-player.

The choice matters when the game app is not installed — for example, the player opens the hub in a mobile browser:

  • A custom scheme (mygame://…) has no operating-system fallback. If nothing on the device handles the scheme, the browser does nothing and the player is left on the loading spinner. Your apple-app-site-association and assetlinks.json files do not apply to custom schemes.
  • An https App Link / Universal Link falls back automatically: the OS opens your app when it is installed, and otherwise the browser loads that https URL normally. Point that URL at an endpoint on your server that redirects the player wherever you want them to land when the app is missing (for example, the web store), so they are never stuck.

To enable App Links / Universal Links, host assetlinks.json (Android) and apple-app-site-association (iOS) on the domain used in your Deep Link URL, and have your app claim the corresponding path.

When the player clicks the login button, the game hub opens your Deep Link URL with the nonce appended. The URL will resemble the following format:

https://your-game-server.com/authorize-player?nonce=<value>

Here, <value> is a unique string generated by the game hub for each authorization request.

The Game Client (or, for an https App Link that the app is not installed to handle, your server) 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:

ParameterDescriptionRequired?
player_idThe unique identifier for the player to be authorized.Yes
nonceThe unique string provided by the game hub.Yes
redirect_pathThe game hub page to redirect the player to.No
player_infoOptional 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:

ParameterDescriptionRequired?
nonceThe unique string provided by the game hub, taken from the authorization deep link.Yes
reasonThe 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 [email protected]

On this page