OAuth URLs & URL Construction

Detailed documentation including all of the options for construction your app or game's HYPLAY OAuth url

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 ParameterPurposeExample
redirectUriThe uri to redirect the user to once they've approved or denied the auth request.redirectUri=https://login.hytopia.com
responseTypeThe 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
appIdThe HYCHAIN application id the user is authorizing.appId=7bb340e3-3963-4c2f-9fcc-898e3ce73fa2
chainThe 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
stateArbitrary state used by the application that is passed through the authorization process to the redirect uri.state={"username":"ark","flow":"preregister"}
scopesThe 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
nativeAllowanceThe 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
contractFunctionSelectorsA 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)" ], } ]
erc20AllowancesA 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" } ]
erc721AllowancesA 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"] } ]
erc1155AllowancesA 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" ] } ]
expiresAtWhen 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