Skip to main content

Social Authentication on Game Hub

Aghanim supports multiple social login providers (e.g., Apple, Discord, Facebook, Google) and generic OIDC-compliant providers for player authentication via webhooks. These webhooks notify your backend of a login event, requiring validation of the OAuth2 authorization code to grant or deny access to the Game Hub.

Requirements

To process player verification events from Aghanim using social login, your server must:

  • Expose an HTTPS POST endpoint.
  • Accept webhook events signed by Aghanim.
  • Exchange the provided code (an authorization code obtained via the OAuth2 Authorization Code Grant flow using response_type=code) for an access token with the appropriate provider.
  • Validate and match the resulting user profile against your player database.
  • Respond with a 200 status code and JSON payload for success or failure.

Supported Providers

You must configure each social provider in your game application dashboard and ensure proper Redirect URI handling for OAuth2 flows. The following providers are currently supported:

  • Apple
  • Discord
  • Google
  • Facebook
  • OIDC (any OpenID Connect-compliant provider)
info

For providers not listed above, you can use the generic OIDC Login plugin to integrate any OpenID Connect-compliant identity provider (e.g., Keycloak, Auth0, Okta, Azure AD). If you need further assistance, please contact us.

OAuth2 Redirect URIs

For each provider, ensure the following Redirect URI is added in the respective developer console:

https://<GAME_HUB_DOMAIN>/oauth2/<PROVIDER>/callback

Replace <GAME_HUB_DOMAIN> with your game hub's domain (e.g., demo.aghanim.com) and <PROVIDER> with facebook, google, apple, discord, or oidc.

Provider-Specific Configuration

info

While the general OAuth2 flow is consistent across providers, setup steps differ slightly per platform. Detailed setup instructions can be found on each provider’s developer documentation.

Apple

  1. Go to Apple Developer Portal
  2. Register a new Sign In with Apple service under Identifiers
  3. Configure your Services ID and Redirect URI
  4. Generate a client secret JWT for OAuth2 token exchange

Discord

  1. Visit Discord Developer Portal
  2. Create an application and enable OAuth2
  3. Set your Redirect URI

Facebook

  1. Go to Facebook Developers
  2. Create a new app (type: Consumer)
  3. Add Facebook Login product
  4. Under Facebook Login → Settings, configure:
    • Client OAuth Login: Yes
    • Use Strict Mode for Redirect URIs: Yes
  5. Set your Redirect URI in Valid OAuth Redirect URIs

Google

  1. Go to Google Cloud Console
  2. Create OAuth2 credentials under APIs & Services → Credentials
  3. Configure the Redirect URI

OIDC

  1. Configure a client application in your OIDC-compliant identity provider (e.g., Keycloak, Auth0, Okta, Azure AD)
  2. Note the Discovery URL, Authorization Endpoint, and Client ID
  3. Set your Redirect URI
  4. See the OIDC Login guide for detailed setup instructions

Configuration

Register your endpoint via:

Request Schema

Below is an example of an player.verify webhook request:

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "player.verify",
  "event_data": {
    "method": "google",
    "code": "4/0123abc...xyz"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.login",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

The Event schema

KeyTypeDescription
event_idstringUnique Event ID generated by Aghanim.
game_idstringYour game ID in the Aghanim system.
event_typestringThe type of the event, player.verify in this case.
event_timenumberEvent date in Unix epoch time.
event_dataEventDataContains the event-specific data, with possible keys for inherited objects.
idempotency_keystring|nullEnsures webhook actions are executed only once, even if retried. Can be null depending on event type.
request_idstring|nullIf the event was triggered by an API request, the request ID is included.
sandboxbooleanIndicates whether the event was sent from the sandbox game environment.
triggerstring|nullThe trigger that caused the event to be sent.
transaction_idstringThe transaction ID generated by Aghanim. This ID may be the same for multiple events emitted within the same transaction.
contextobject|nullContextual information about the event.

EventData Schema

KeyTypeDescription
methodstringThe provider used for authentication. One of apple, discord, facebook, google, or oidc.
codestringThe authorization code generated by the provider. See RFC 6749 Section 4.1.2 for details.
redirect_uristring|nullThe redirect URI used in the original authorization request. See RFC 6749 Section 4.1.3 for details. Included for providers that require it during token exchange (e.g., OIDC). null for other providers.

Processing the Webhook

Your backend should:

  1. Extract method, code, and redirect_uri from the request body.
  2. Exchange code for an access token using the corresponding provider's OAuth2 token endpoint. If redirect_uri is not null, include it in the token exchange request.
  3. Fetch the user profile using the access token.
  4. Match the social account to a player in your database.
  5. Respond with the appropriate webhook response schema to accept or deny login.

Successful Response Schema

Please refer to the player.verify webhook response documentation for expected structure.

Failure Response Schema

If the verification fails, respond with a 200 status code and the following JSON response:

{
  "status": "error",
  "code": "not_found",
  "message": "Player not found"
}

List of possible error codes:

  • not_found - The account/player not found.
  • invalid_signature - The signature was invalid.
  • validation_error - The request data was invalid.
  • banned - The account/player is banned.

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

On this page