# Account & Authentication

## Authentication for Browser-Based Game

{% hint style="info" %}
If you are not making browser-based game, please skip this step and continue to [Authenticating Using KOMO Account](#authenticating-using-komo-account) API
{% endhint %}

1. User will access your game from within Komoverse website
2. Komoverse website will check if user logged in or not
3. If user not logged in, Game URL will be accessed via iframe without authorization token for example <mark style="color:red;"><https://yourgameurl.com/index.html></mark>&#x20;
4. If user logged in, Game URL will be accessed via iframe with given authorization token for example <mark style="color:red;"><https://yourgameurl.com/index.html?token=eyxxx......xxxx></mark>
5. You can use the token given in URL parameter to make Authorized Player API calls
6. Please note that token have expiry time. Don't forget to refresh the token.

## Authenticating Using KOMO Account

## Login with KOMO Account

<mark style="color:green;">`POST`</mark> `[endpoint]/v3/login`

#### Query Parameters

| Name                                             | Type   | Description   |
| ------------------------------------------------ | ------ | ------------- |
| komo\_username<mark style="color:red;">\*</mark> | String | KOMO Username |
| password<mark style="color:red;">\*</mark>       | String | User Password |

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| X-Api-Key<mark style="color:red;">\*</mark> | String | API Key     |

{% tabs %}
{% tab title="200: OK Success login response" %}

```json
{
    "status": "success",
    "expires_at": {
        "unix": 1685522166,
        "utc": "2023-05-31 08:36:06"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxIiwianRpIjoiODE0NzhhMWY3NzY5ZmE3YjFkYjJiNmNhNTBmYTEzZTJhN2ZiZmE5ZjY0MjFmZjE4MGIyYmQ4YzNjYjIwNDljMTJjM2U3MTE4ZGZiZTE1MzIiLCJpYXQiOjE2ODU1MTg1NjYuMjkzNTA0LCJuYmYiOjE2ODU1MTg1NjYuMjkzNTA4LCJleHAiOjE2ODU1MjIxNjYuMjUwOTM2LCJzdWIiOiIxMDAyNCIsInNjb3BlcyI6W119.Yqerxk3m5MeRLJYNL9JWuS__lPo-MFXjGpHD18o1KAO3d1yjjW_mPs5dXmggrBBT53PWa0G-WBWe18-0qQu5KrS-V8MQbhuccxJbZMZmFzmEosmdIQC6ZXh353mlmFqcCJXC1_iegaJv1VsD0JwbcF61j3-5txrbX2M_HpANW2yT15RTGgptKmjwMj04hy1AyiTFvLDm5WCDwY_ld4znxzqfoo3aTpZVhgiD9VwqhxmT9OXjki55EVWGJw5yX1Ccx-YPz26O1m0hfTaTMco1u7Lw_cnwLyqbgmTb6s3CpLnVLszXJCq0J27PeV5osTaO4lC9g4GDrS_tSd8MzYkToSGLh0Y6S9nTKQypNEcqTjZ19T_kujmA-6ovEM3H9AnXAqYBm7Wnfoa4eu5U1A_FdN6XMXxeUlyzHsbwDetCqYVRbxEUAk7qRmK8_CshytvEgWEbzj4nY9zRdwTi6JHG6bA4_FW0-CtFmSphgLqf-kKL6rxHR1tH9WpCm6Y_7J8ccqBmKnW930lQDc6CFtEQ0iHr-lvmdN0ebW0DWNdIepAqUAGFeNhTU1WPXnx0PRFw8otZ-HIuKj76yejPmxFHuuXkkbes4M3whaMs7R2IoCpEXNVXuV39wnMzhvdnUJHVjyee-VH3YWKIlP5WWrXVIFY3o6hhd4l-_VGqJYOPzYA"
}
```

{% endtab %}

{% tab title="403: Forbidden Username or password is incorrect" %}

```json
{
    "status": "error",
    "messages": {
        "unauthorizedLogin": "The username or password is incorrect."
    }
}
```

{% endtab %}

{% tab title="403: Forbidden Wrong password" %}

```json
{
    "status": "error",
    "messages": {
        "incorrectPassword": "The password you have entered is not correct."
    }
}
```

{% endtab %}
{% endtabs %}

## Authenticating Using Third Party Providers

## Login with Google or Facebook Single Sign-On

<mark style="color:green;">`POST`</mark> `[endpoint]/v3/single-sign-on`

If your game have integrated Google / Facebook SSO, you can send SSO access token to this API. If the email associated with SSO account already registered on a KOMO Account, we will send you our access token to be used in game.

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| X-Api-Key<mark style="color:red;">\*</mark> | String | API Key     |

#### Request Body

| Name                                       | Type             | Description                                    |
| ------------------------------------------ | ---------------- | ---------------------------------------------- |
| token<mark style="color:red;">\*</mark>    | String           | Token from Google, Facebook, etc               |
| provider<mark style="color:red;">\*</mark> | String           | Provider name like "google, facebook, discord" |
| otp                                        | numeric, 6 digit | otp code from email                            |

{% tabs %}
{% tab title="200: OK Successfully Login" %}

```json
{
    "status": "success",
    "expires_at": {
        "unix": 1685522166,
        "utc": "2023-05-31 08:36:06"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxIiwianRpIjoiODE0NzhhMWY3NzY5ZmE3YjFkYjJiNmNhNTBmYTEzZTJhN2ZiZmE5ZjY0MjFmZjE4MGIyYmQ4YzNjYjIwNDljMTJjM2U3MTE4ZGZiZTE1MzIiLCJpYXQiOjE2ODU1MTg1NjYuMjkzNTA0LCJuYmYiOjE2ODU1MTg1NjYuMjkzNTA4LCJleHAiOjE2ODU1MjIxNjYuMjUwOTM2LCJzdWIiOiIxMDAyNCIsInNjb3BlcyI6W119.Yqerxk3m5MeRLJYNL9JWuS__lPo-MFXjGpHD18o1KAO3d1yjjW_mPs5dXmggrBBT53PWa0G-WBWe18-0qQu5KrS-V8MQbhuccxJbZMZmFzmEosmdIQC6ZXh353mlmFqcCJXC1_iegaJv1VsD0JwbcF61j3-5txrbX2M_HpANW2yT15RTGgptKmjwMj04hy1AyiTFvLDm5WCDwY_ld4znxzqfoo3aTpZVhgiD9VwqhxmT9OXjki55EVWGJw5yX1Ccx-YPz26O1m0hfTaTMco1u7Lw_cnwLyqbgmTb6s3CpLnVLszXJCq0J27PeV5osTaO4lC9g4GDrS_tSd8MzYkToSGLh0Y6S9nTKQypNEcqTjZ19T_kujmA-6ovEM3H9AnXAqYBm7Wnfoa4eu5U1A_FdN6XMXxeUlyzHsbwDetCqYVRbxEUAk7qRmK8_CshytvEgWEbzj4nY9zRdwTi6JHG6bA4_FW0-CtFmSphgLqf-kKL6rxHR1tH9WpCm6Y_7J8ccqBmKnW930lQDc6CFtEQ0iHr-lvmdN0ebW0DWNdIepAqUAGFeNhTU1WPXnx0PRFw8otZ-HIuKj76yejPmxFHuuXkkbes4M3whaMs7R2IoCpEXNVXuV39wnMzhvdnUJHVjyee-VH3YWKIlP5WWrXVIFY3o6hhd4l-_VGqJYOPzYA"
}
```

{% endtab %}

{% tab title="400: Bad Request Missing token and provider" %}

```json
{
    "status": "error",
    "message": {
        "token": [
            "The token field is required."
        ],
        "provider": [
            "The provider field is required."
        ]
    }
}
```

{% endtab %}

{% tab title="404: Not Found Account Not Found" %}

```json
{
    "status": "error",
    "messages": "Account is not Found. Please Register!"
}
```

{% endtab %}
{% endtabs %}

## Linked Game Account

## Find Linked Game Account by Authorization Header

<mark style="color:blue;">`GET`</mark> `[endpoint]/v3/account/linked/get`

If your game have it's own game account, you can check whether this KOMO Account linked to your game or not with this API

#### Headers

| Name                                            | Type   | Description  |
| ----------------------------------------------- | ------ | ------------ |
| X-Api-Key<mark style="color:red;">\*</mark>     | String | API Key      |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer Token |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "status": "success",
    "data": {
        "komo_username": "kokomo",
        "provider": "game_id",
        "provider_user_id": "1476784473869930500"
    }
}
```

{% endtab %}
{% endtabs %}

## Create KOMO Access Token by Linked Account

<mark style="color:blue;">`GET`</mark> `[endpoint]/v3/account/linked/authorize`

<mark style="color:red;">WARNING: This API only used after successful login with your own Game Account. If you use KOMO Account login, this API is not needed.</mark>

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| X-Api-Key<mark style="color:red;">\*</mark> | String | API Key     |

#### Request Body

| Name                  | Type   | Description          |
| --------------------- | ------ | -------------------- |
| provider\_account\_id | String | Your Game Account ID |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "status": "success",
    "expires_at": {
        "unix": 1687758196,
        "utc": "2023-06-26 05:43:16"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxIiwianRpIjoiYjNkNjRlZmY3N2RmZmZjOWM5MWE1OGUxZDEwYzA4MjNiYmRhYTc1Nzc5ZDJkZGJhOGJmMzNhODM2YWZlYzg5MGM3M2IxZmNhYTFlODc5MTMiLCJpYXQiOjE2ODc3NTQ1OTYuODY5NzA5LCJuYmYiOjE2ODc3NTQ1OTYuODY5NzEyLCJleHAiOjE2ODc3NTgxOTYuODI1MjkyLCJzdWIiOiIxMDAxNyIsInNjb3BlcyI6W119.j-S77B-_SI9Ekv9mniC3M0to9XvsSzgN9wKkWNe0sgKq72HvbmOiQb9yOv-KxXLxI_5g4IWYu7AnMTbPo2mpbJoreEBQLx4N7PRkz7Mqzc5Pw_E_azoT1mQxCX5BxEabEa8IiZV8EFpQrayPMBnR5fNtSfAmsI3yFX1YzkgKudcd8x1oMWXIJFm2QCp0bPt7_zifeZRxyBvYOqWvRC1hkhCTDQt3J-y9rTL0-cUdlMbDEhsZvxhpriEm0OCIJC0CNMWLlbXPIltMbr5egZtikZ1d9c7oiMTKMgeVRbSlmcOaD2fS3iNWM2hlF8uc9Tqh0-5sPXCQ96P3Z1hdBSF5katJ-MTz0VtkvtxZpYl-VjxE9G9Hh3aPRbSvqlgy-N922-1IZxNRQY9FHkdBMnXmV_UR2m2-fYryPHnc-kxoQqTiJ7E4pcIb4e415DL_MHpvlG6K9CFEJLgCdXUDa0WMpKhK5QGGVOwBE-LvPzBkwDTSDc1jWGEJc0qLbOK4p_SXCeUTjioW55yVyD_dCVv1muhJ4uCp6OOyjgP3pleSDRpgNgo07udU0xZKpEBaVPMHrcLNaEtl3GbGRwesC1jnflmUYR8Lq-TMVxl3W9lj83aN90SicCSVhd1qfV_unCwgGar4SVajVhE0fQnzzxW2m2AaxKB_NtcJGTjTsbSukUk"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```json
{
    "status": "error",
    "messages": "Linked KOMO Account Not Found for This Game"
}
```

{% endtab %}
{% endtabs %}

## Managing KOMO Access Token

## Check Token Validity

<mark style="color:blue;">`GET`</mark> `[endpoint]/v3/token/check`

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Token bearer from auth |

{% tabs %}
{% tab title="200: OK Successfully check token " %}

```json
{
    "status": "success",
    "message": "Token is valid!",
    "expires_at": {
        "unix": 1685524564,
        "utc": "2023-05-31 09:16:04"
    }
}
```

{% endtab %}

{% tab title="404: Not Found Token is invalid" %}

```json
{
    "status": "error",
    "messages": "Unauthenticated."
}
```

{% endtab %}
{% endtabs %}

## Refresh Token

<mark style="color:blue;">`GET`</mark> `[endpoint]/v3/token/refresh`

Renew token expiry time by refreshing the token. New access token will be provided and further request should use new access token instead of old access token.

#### Headers

| Name                                            | Type   | Description  |
| ----------------------------------------------- | ------ | ------------ |
| X-Api-Key<mark style="color:red;">\*</mark>     | String | API Key      |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer Token |

{% tabs %}
{% tab title="200: OK Refresh Token Successfully" %}

```json
{
    "status": "success",
    "expires_at": {
        "unix": 1685522043,
        "utc": "2023-05-31 08:34:03"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxIiwianRpIjoiMTFjNzAyYzYzNDIyYWFkNDM5YmViMzc4NWIyMGMzYWQ3ZmM1MmJhNzQ5YjMwZjNjZGMxYjE4NDJjODAzMDZhODI5NDZjMTNlZTFkOGM1ODIiLCJpYXQiOjE2ODU1MTg0NDMuNzIyMjE0LCJuYmYiOjE2ODU1MTg0NDMuNzIyMjE5LCJleHAiOjE2ODU1MjIwNDMuNjY4OTk0LCJzdWIiOiIxMDAyNCIsInNjb3BlcyI6W119.jxqNunHWc7GySbV5oLtBBDWUoYQDvLVUBzqAXCaXR2qiGfUpAaK67xNuKFuiytX7fK5pEEoaFvbslBzZfM38g3-5T9gVl__U9D7dVZdcLXA70fO-tpd0mAJ4hi26P4W6QTRmTEWKLE0A634edS1kFJXM1goStzpuhDph7BudC6RfMBY0d4YPGM7tftAoLNo2PfqbZJT4zgHuShqHYb15NNCPDNxsNcjv1709FUO-xAjRzG3aR4OhIELO-QnMglNwJcdWbfQHilQWPgS1sn7g1kQtVgbGoPJ7NSelgC0h13JMMut2Il3n-DTJRcj6eTI9Cix55ZU59dGoA7rU9zmWf9QTrJ3GFckrv77T64qp_WrTyy6craVUIr59L-Yxu1S2Kt0sIQv9hq237RN_G2YfYNPeTBk4IGUgehUwx-dBDnm4IYFFwYi0PDRAl99R9Euf8gN306shBRVUIxA2-BN9lnOagiEhBbjfix8mEW6WUtwKhFB_nzjMBl6eC7cebdKXgXURi1P0QaG2vvpidNld7hSJasnaRaxP5XPcTD5Sn0NZ8kjYSiBte3Wwwah6BQOHypX4oecdhP2wvpFJhWdtwCcKZUw_MFhCmjCAjEJqHnziedu8h86SvupCLJjdPzsnTqmLEqjgt-9YX9eQeMMwFTjZiOFKXAbRCg4N_Z0KDcw"
}
```

{% endtab %}

{% tab title="403: Forbidden Error Token Required" %}

```json
{
    "status": "error",
    "messages": {
        "tokenRequired": "A login token is required to perform this request."
    }
}
```

{% endtab %}

{% tab title="403: Forbidden Error Api-key Required" %}

```json
{
    "status": "error",
    "messages": {
        "apiKeyRequired": "An API key is required to perform this request. If you wish to use the KOMO API in your application, contact the Komoverse team to reach out for an agreement."
    }
}
```

{% endtab %}
{% endtabs %}

## Using the KOMO Account

## Get Account Information from Authentication Header

<mark style="color:blue;">`GET`</mark> `[endpoint]/v3/account/me`

#### Headers

| Name                                            | Type   | Description  |
| ----------------------------------------------- | ------ | ------------ |
| X-Api-Key<mark style="color:red;">\*</mark>     | String | API Key      |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer Token |

{% tabs %}
{% tab title="200: OK Get Account Information Successfully" %}

```json
{
    "status": "success",
    "data": {
        "id": 10024,
        "komo_username": "polycrest",
        "in_game_display_name": "polycrest",
        "profile_picture_url": "https://komo.s3.ap-southeast-1.amazonaws.com/profile-account/kokomo-XYXJ.jpg",
        "country": "IDN",
        "primary_language": "en",
        "shard": 500222
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Token Field is Required" %}

```json
{
    "status": "error",
    "message": {
        "token": [
            "The token field is required."
        ]
    }
}
```

{% endtab %}

{% tab title="403: Forbidden API-Key is Required" %}

```json
{
    "status": "error",
    "messages": {
        "apiKeyRequired": "An API key is required to perform this request. If you wish to use the KOMO API in your application, contact the Komoverse team to reach out for an agreement."
    }
}
```

{% endtab %}

{% tab title="403: Forbidden Token is Required" %}

```json
{
    "status": "error",
    "messages": {
        "tokenRequired": "A login token is required to perform this request."
    }
}
```

{% endtab %}
{% endtabs %}

## Find Other User's KOMO Account

<mark style="color:green;">`POST`</mark> `[endpoint]/v3/account/find`

Find Other KOMO Account by its user ID, KOMO username, game display name, or wallet address

#### Query Parameters

| Name                                            | Type   | Description                                                                                                                                                             |
| ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| exact\_match                                    | Enum   | 0 : approximate match, 1 : exact match (default 0)                                                                                                                      |
| search\_query<mark style="color:red;">\*</mark> | String | Search Query (min: 3 character)                                                                                                                                         |
| search\_column                                  | String | Column to search (support: `id, komo_username, in_game_display_name, wallet_pubkey`<mark style="color:red;">`both web3 and semi custodial`</mark>) default `all fields` |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "status": "success",
    "data": [
        {
            "id": 10073,
            "komo_username": "ty0000",
            "country": "PHL",
            "in_game_display_name": "ty0002",
            "profile_picture_url": "https://hub.komoverse.io/assets/profile_pic/6392f3de3fe95.jpg",
            "wallet_pubkey": "2aXTwjGcRh6BuDoAi4USRnG2pwj8BpJvZB6CY37ikLLS",
            "semi_custodial_wallet_pubkey": null
        },
        {
            "id": 10199,
            "komo_username": "ty0001",
            "country": "PHL",
            "in_game_display_name": "ty0001",
            "profile_picture_url": null,
            "wallet_pubkey": null,
            "semi_custodial_wallet_pubkey": null
        }
    ]
}
```

{% endtab %}
{% endtabs %}