All authentication flows through the HYPLAY Authentication systems. These systems implement most of the OAuth 2.0 standard for a familiar developer experience.

HYPLAY authentication allows players across the entire HYCHAIN ecosystem to only need a singular account, through HYPLAY to log into and use any apps or play any games without needing multiple accounts. This also allows direct liquidity interoperability.

HYPLAY and our authentication flows also simplify the needs for players directly having to interact with a wallet, gas fees, and transactions - all of this is managed behind the scenes in a permissioned & fully self-custodied manner that yields an overall user experience that feels as frictionless as any non-web3 app or game.

OAuth URL Construction

The default HYPLAY OAuth base url is: https://hyplay.com/oauth/authorize

The default OAuth url will automatically recognize if the user is already signed into a HYPLAY account and immediately prompt them to authorize your app, simplifying their overall auth flow. If they are not signed into a HYPLAY account, it will prompt them with HYPLAY's sign in screen. This sign in screen will also handle account creation if they do not have an existing HYPLAY account.

Alternatively, you may want a user to always be prompted to sign into their HYPLAY account when they are directed to your app's OAuth URL, to achieve this, use the base url: https://hyplay.com/oauth

To construct your OAuth url, append the desired query parameters for your use case to either of the base urls above.

For example, this is a fully constructed OAuth URL from our HYPLAY Demo App:

OAuth Url Query Parameter Reference

Query Parameter	Purpose	Example
redirectUri	The uri to redirect the user to once they've approved or denied the auth request.	`redirectUri=https://login.hytopia.com`
responseType	The response type for the redirect uri. Can be one of the following: `code`: Returns an exchange code appended to the redirect uri as `#code=exchange_code`- This code must then be used in combination with the application secret by the application's backend to retrieve a session access token for the user. `token`: Returns a session access token to the redirect uri as `#token=access_token`- This is a less secure authorization approach, but may be necessary for mobile apps, or single page applications that don't have a backend.	`responseType=code`
appId	The HYCHAIN application id the user is authorizing.	`appId=7bb340e3-3963-4c2f-9fcc-898e3ce73fa2`
chain	The chain the user is approving the authorization for. Can be one of the following: `HYCHAIN`: HYCHAIN's mainnet `HYCHAIN_TESTNET`: HYCHAIN's testnet	`chain=HYCHAIN`
state	Arbitrary state used by the application that is passed through the authorization process to the redirect uri.	`state={"username":"ark","flow":"preregister"}`
scopes	The user data scopes requested, by default the basic profile scope is included, in which case this parameter can be omitted. Allowed scopes are: `profile`: Included by default, even if omitted. This allows access to the user's username, wallet address, id, profile picture, etc. `email`: The user's email address, if available. `socialId`: If the user registered using a social account, allows retrieval of the user's social id and account type.	`scopes=profile,email,socialId`
nativeAllowance	The maximum amount of native token ($TOPIA) the application requires the ability to spend on behalf of the user during the session. This should be provided in decimal format. If up to 125.5 $TOPIA needs to be spent, 125.5 is the value that should be provided.	`nativeAllowance=125.5`
contractFunctionSelectors	A JSON array of contracts and contract functions the application is allowed to invoke on behalf of the user through their session. Must be a JSON array of objects conforming to the schema: `{"address": "0x..", "functionSelectors": ["transfer(address,uint256)", "0xa22cb465"] `functionSelectors` may be an array of bytes4 function selectors, or complete function signatures - or a combination of the two.	`[ { "address": "0xB40cdD7599d8f52C48f29E10CFBf24918C85F7cC", "functionSelectors": [ "transfer(address,uint256)", "0xa22cb465" ], }, { "address": "0xcccCb68e1A848CBDB5b60a974E07aAE143ed40C3", "functionSelectors": [ "approve(address,uint256)", "0xb37cb465", "burn(uint256)" ], } ]`
erc20Allowances	A JSON array of erc20 contracts and maximum allowances the application is allowed to transfer or approve on behalf of the user through their session. Must be a JSON array of objects conforming to the schema: `{"address":"0x...", "allowance": "1.521"}` `allowance` should not be in 1e18 format, as a typical uint256 would be, instead decimal format.	`[ { "address": "0xcccCb68e1A848CBDB5b60a974E07aAE143ed40C3", "allowance": "321.23461" }, { "address": "0x8d9710f0e193d3f95c0723eaaf1a81030dc9116d", "allowance": "10500.50" } ]`
erc721Allowances	A JSON array of erc721 contracts, a approveAll or specific token ids the application is allowed to transfer or approve on behalf of the user through their session. Must be a JSON array of objects conforming to the schema: `{"address":"0x...", "approveAll":false, "tokenIds": ["421", "123" ...]` If `approveAll` is provided, `tokenIds` may be omitted, as all tokenIds are approved	`[ { "address": "0x98e62fe371519d1d07e6f5bfce04737d4dacabfd", "approveAll": true }, { "address": "0x2e3b7f1f9f3f0f1f1f1f1f1f1f1f1f1f1f1f1f1f", "approveAll": false, "tokenIds": ["41", "23"] } ]`
erc1155Allowances	A JSON array or erc1155 contracts, a approvaAll or specific token ids and token id allowances the application is allowed to transfer or approve on behalf of the user through their session. Must be a JSON array of objects conforming to the schema: `{"address": "0x...", "approveAll": false, "tokenIds": ["421", "123", ...], "allowances": ["10", "51"]}` If `approveAll` is provided, `tokenIds` and `allowances` may be omitted, as all tokenIds for any allowance are approved.	`[ { "address": "0x98e62fe371519d1d07e6f5bfce04737d4dacabfd", "approveAll": true }, { "address": "0x2e3b7f1f9f3f0f1f1f1f1f1f1f1f1f1f1f1f1f1f", "approveAll": false, "tokenIds": ["41", "23"], "allowances": [ "10", "50" ] } ]`
expiresAt	When the session expires. If omitted, defaults to expiring 24 hours from the time the session is created. Must be a valid timestamp in seconds.	`expiresAt=1744169893`
referrerId	The user id that referred the authorizing user to the app.	`referrerId=e8745a01-8ad2-4fa0-8b5d-e617a6932825`