🔓Account & Authentication

Authentication for Browser-Based Game

If you are not making browser-based game, please skip this step and continue to Authenticating Using KOMO Account API

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 https://yourgameurl.com/index.html

4. If user logged in, Game URL will be accessed via iframe with given authorization token for example https://yourgameurl.com/index.html?token=eyxxx......xxxx

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

POST [endpoint]/v3/login

Query Parameters

Name	Type	Description
komo_username*	String	KOMO Username
password*	String	User Password

Headers

Name	Type	Description
X-Api-Key*	String	API Key

200: OK Success login response

{
    "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"
}

403: Forbidden Username or password is incorrect

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

403: Forbidden Wrong password

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

Authenticating Using Third Party Providers

Login with Google or Facebook Single Sign-On

POST [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*	String	API Key

Request Body

Name	Type	Description
token*	String	Token from Google, Facebook, etc
provider*	String	Provider name like "google, facebook, discord"
otp	numeric, 6 digit	otp code from email

200: OK Successfully Login

{
    "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"
}

400: Bad Request Missing token and provider

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

404: Not Found Account Not Found

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

Linked Game Account

Find Linked Game Account by Authorization Header

GET [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*	String	API Key
Authorization*	String	Bearer Token

200: OK

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

Create KOMO Access Token by Linked Account

GET [endpoint]/v3/account/linked/authorize

WARNING: This API only used after successful login with your own Game Account. If you use KOMO Account login, this API is not needed.

Headers

Name	Type	Description
X-Api-Key*	String	API Key

Request Body

Name	Type	Description
provider_account_id	String	Your Game Account ID

200: OK

{
    "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"
}

400: Bad Request

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

Managing KOMO Access Token

Check Token Validity

GET [endpoint]/v3/token/check

Headers

Name	Type	Description
Authorization*	String	Token bearer from auth

200: OK Successfully check token

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

404: Not Found Token is invalid

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

Refresh Token

GET [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*	String	API Key
Authorization*	String	Bearer Token

200: OK Refresh Token Successfully

{
    "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"
}

403: Forbidden Error Token Required

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

403: Forbidden Error Api-key Required

{
    "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."
    }
}

Using the KOMO Account

Get Account Information from Authentication Header

GET [endpoint]/v3/account/me

Headers

Name	Type	Description
X-Api-Key*	String	API Key
Authorization*	String	Bearer Token

200: OK Get Account Information Successfully

{
    "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
    }
}

400: Bad Request Token Field is Required

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

403: Forbidden API-Key is Required

{
    "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."
    }
}

403: Forbidden Token is Required

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

Find Other User's KOMO Account

POST [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*	String	Search Query (min: 3 character)
search_column	String	Column to search (support: id, komo_username, in_game_display_name, wallet_pubkeyboth web3 and semi custodial) default all fields

200: OK

{
    "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
        }
    ]
}