Skip to main content

Social Authentication on the 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.

FAQ

Do I need to share my OAuth credentials with Aghanim?

No. Aghanim never needs access to your OAuth client secret or API keys. When a player logs in via a social provider on the game hub, Aghanim receives an authorization code from the provider and forwards it to your backend through the player.verify webhook. Your server then exchanges that code for an access token using your own credentials — the same ones your game already uses.

Do I need to create a separate OAuth app for Aghanim?

No. You should use the same OAuth application that your game already uses. The only change required is adding the Aghanim Redirect URI to your existing app's allowed redirect URIs in the provider's developer console.

What about providers with app-scoped IDs (Meta, Apple)?

Providers like Meta (Facebook) and Apple issue player IDs that are scoped to a specific OAuth application. Since Aghanim uses your existing OAuth app (not a separate one), the player IDs returned during token exchange will be the same IDs your game already knows. There is no ID mismatch.

Need help?
Contact our integration team at [email protected]

On this page