# Composite Authorization

## Overview

Aghanim provides a method to authorize players using a Composite Authorization, where Player Identity may consists of multiple fields that uniquely identify a player. This method allows you to configure a custom login form on the Game Hub that prompts players to enter multiple identifiers to authenticate their identity.

For example, you may configure a Composite Authorization with fields such as:

*   `account_id`
*   `server_id`
*   `character_id`

> **WARNING:** The parameters listed above are examples, and the actual parameters may vary based on your specific implementation.

## Prerequisites

*   Access to your Aghanim account.
*   Administrative permissions to create and manage player identities.
*   Configured Composite User ID login type in [**Game** → **Settings**](https://dashboard.aghanim.com/go/settings/login).

## Step 1: Handle `player.lookup` Webhook for Partial Identity

When Aghanim sends a `Lookup Player` webhook to your server with a partial Composite Authorization fields, your server can respond with the remaining Player Identity fields to authorize players associated with the partial identity.

### Example Webhook Request:

```js
{
  "account_id": "123456"
}
```

### Example Webhook Response:

```js
{
  "status": "ok",
  "data": [
    {
      "name": "PlayerOne",
      "avatar_url": "https://example.com/avatar1.png",
      "player": {
        "account_id": "123456",
        "server": {"id": "gerund-23", "name": "Gerund 23"},
        "character_id": "4tgk-kj8xz"
      },
    },
    {
      "name": "PlayerTwo",
      "avatar_url": "https://example.com/avatar2.png",
      "player": {
        "account_id": "123456",
        "server": {"id": "goron-73", "name": "Goron 73"},
        "character_id": "4d4r-iopb2"
      },
    },
  ]
}
```

### Example of failure response:

Return with 200 status code and the following JSON response:

```js
{
  "status": "error",
  "code": "not_found",
  "message": "Account 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.

Your server must handle this webhook to provide the remaining Composite Authorization fields necessary for player authorization in the Game Hub login form.

## Step 2: Handle `player.verify` Webhook for Composite Authorization

When Aghanim sends a [Verify Player (`player.verify`)](https://docs.aghanim.com/webhooks/verify-player.md) webhook to your server with a Composite Authorization, you can authorize the player using the provided Composite Authorization.

### Example Webhook Request:

```js
{
  "player": {
    "account_id": "123456",
    "server_id": "gerund-23",
    "character_id": "4tgk-kj8xz"
  }
}
```

### Example Webhook Response:

```js
{
  "status": "ok",
  "data": {
    "name": "PlayerOne",
    "avatar_url": "https://example.com/avatar.png",
    "attributes": {
      "level": 2
    },
    "country": "US",
    "player": {
      "account_id": "123456",
      "server": {"id": "gerund-23", "name": "Gerund 23"},
      "character_id": "4tgk-kj8xz"
    }
  }
}
```

### Example of failure response:

Return with 200 status code and the following JSON response:

```js
{
  "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.

## Step 3: Implement Deep Linking for Auto-Login

Create a deep link URL with the Composite Authorization fields to enable auto-login for the player on the Game Hub.

### Example:

```text
https://<GAME_HUB_URL>/go/login?account_id=123456&server_id=gerund&character_id=4tgk-kj8xz
```

When the player opens this URL, the Game Hub will automatically log in the player using the provided Composite Authorization fields.

By implementing this optional step, your application can provide a richer and more connected player experience by making it easier for users to access and manage all of their related player identities.

---
Source: https://docs.aghanim.com/advanced/composite-authorization