Ecosystem & SSO Setup
Ecosystems
MetaFab Ecosystems are a powerful way to support a network of games with a consistent and standard single sign-on auth flow across them to enable new degrees of game interoperability, frictionless player experiences, and more. You can learn more details about how Ecosystems work here.
Create an Ecosystem Account
Before we dive in, you'll need to create an Ecosystem account. You can do this through the create Ecosystem API endpoint here.
Branding
You can quickly brand the look and feel of your entire Ecosystem's single sign-on flow using the update Ecosystem API endpoint.
You can set and update branding parameters for your Ecosystem through the update Ecosystem endpoint are:
-
name
: This is the name of your Ecosystem shown on the single sign-on flow. -
iconImageBase64
: This is the image used for the icon at the top of your single sign-on flow. This parameter is set as a base64 representation of the image you want to use. You can use tools like https://www.base64-image.de/ to convert your image to its base64 version, such asdata:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
-
coverImageBase64
: This is the background image used for your single sign-on flow. This parameter is set as a base64 representation of the image you want to use. You can use tools like https://www.base64-image.de/ to convert your image to its base64 version, such asdata:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
-
primaryColorHex
: The hex color (#05B1A3, for example) to use for the buttons of your single sign-on flow.
Additionally, single sign-on flows use a combination of your Ecosystem's branding and the branding for the game a player is attempting to sign in to. Any games in your Ecosystem should set their name
, iconImageBase64
and coverImageBase64
through the update game API endoint.

A mockup of MetaFab's branded ecosystem single sign on page for Treasure.
Setup & Configuration
All single sign-on flows for Ecosystems by default are set on the base URL: https://accounts.trymetafab.com/oauth
. We also support single sign-on flows through your custom domain or subdomain.
You can configure usage by setting query parameters. These query parameters append to your single sign-on flow's base URL. For example, a valid configured single sign-on flow URL is: https://accounts.trymetafab.com/oauth/?ecosystem=b573c2dc-5e93-4c99-a57f-569480d05204&game=addd8995-50b3-4021-aa61-da7277432b9a&permissions={"version":"1.0.0","0x539bdE0d7Dbd336b79148AA742883198BBF60342":{"chain":"ARBITRUM","scopes":["transfers"],"erc20Limit":"*"}}
See the list of configurable query parameters and their explanations below.
Query Parameter | Explanation | Valid Values |
ecosystem required | This tells the single sign-on flow what Ecosystem to sign into. | Any valid Ecosystem id . For example, b573c2dc-5e93-4c99-a57f-569480d05204 |
game required | This tells the single sign-on flow what game to sign in the ecosystem profile for. | Any valid game id . For example, addd8995-50b3-4021-aa61-da7277432b9a |
redirectUri | A supported redirect uri allowed for the game. You can set allowed game redirect URI's through this endpoint. Including this parameter will redirect the player to this uri after going through the SSO flow. The redirect uri will receive the player profile's accessToken , walletDecryptKey and id in the fragment (#) of the redirect url.Excluding this parameter will set the logged in player profile's accessToken , walletDecryptKey and id as a URL fragment (#) of the auth page after logging in. | A valid redirect uri or base uri for your game. For example,https://game.mywebsite.com ,https://mywebsite.com , http://localhost/game or http://localhost?test=123 |
permissions | Additional permissions the game wants to request for the player's profile. By default, games have the ability to read, transfer, and min to a profile's wallet. Additionally, profile wallets can interact with any contract deployed specifically by the authorized game without additional permissions. Setting permissions allows your game to request interoperability access on assets not created by you or your game that a player profile may have in their wallet. Such as a specific ecosystem ERC20 game currency like $MAGIC, ERC1155 item collections, and 3rd party contracts like Seaport, etc. | A valid single sign on permissions request object. See the Configuring Permissions section below for an example. |
Configuring Permissions
Setting the permissions query parameter by default is optional. If you omit it, your game will request the default player profile permissions which allow you to view all their wallet assets, mint and transfer assets to their profile wallet, and use their wallet credentials to interact with any contracts specifically created for and by your game based on the matching systemId
assigned on-chain to your game (You can learn more about the systemId
for custom contract here if you're curious).
The permissions request object follows a standard format; see the code example below to learn how to configure permissions.
{
"version": "1.0.0", // For now, this is always "1.0.0"
// The following contract permission configuration is an example showing all possible configurables.
"0x539bdE0d7Dbd336b79148AA742883198BBF60342": { // The key is the contract address you want permissions for
"chain": "ARBITRUM", // The chain this contract is on REQUIRED
"scopes": [ // an array of scopes for standard function access OPTIONAL
"transfers", // gives contract function call permission to all standard ERC20/ERC1155 type transfer functions
"approvals" // gives contract function call permission to all standard ERC20/ERC1155 type approval functions
],
"functions": [ // an array of contract specific functions to request permissions for OPTIONAL
"doSomething", // can be any named function of the target contract
"burnThings"
],
"erc20Limit": "*", // If the contract is an ERC20 contract, sets the maximum lifetime amount of token that the game can use from the profile wallet. * = unilimited, 100 = 100 token OPTIONAL
"erc1155Limits": { // If the contract is an ERC1155 contract, sets the maximum lifetime amount of specific item ids the game can use from the profile wallet. OPTIONAL
"1": "10", // Key value pairs mapping item id -> item quantity
"*": "*" // An item id of * means all items, an item quantity of * means unlimited quantity.
}
},
// The following contract permission configuration is an example of what a configured contract permission request may look like
"0x381227255ef6c5d85966b78d13e4b4a4c8719b5e": { // You can include as many or as few external contract addresses as you need to request permission for.
"chain": "ARBITRUM",
"scopes": [ "transfers" ],
"erc1155Limits": { "*": "*" } // This contract permission example is basically saying "My game requests the ability to transfer any quantiy of any assets you hold for contract the Arbitrum contract at address 0x381227255ef6c5d85966b78d13e4b4a4c8719b5e"
},
}
Custom Domain Support
If you'd like to route your Ecosystem's single sign-on flow through a custom domain or subdomain instead of https://accounts.trymetafab.com
, please reach out to our team on Discord to configure this.
Example Flows & Implementation Patterns
We have a few possible patterns you may choose to integrate your single sign-on flow through, depending on your Ecosystem and game needs:
Redirect Pattern
Redirect patterns are common for web-based games or UI's where your players need to be redirected to a page on your game's website or a settings page on the web.
Setting the redirectUri
, your game may choose to link a "Sign In With ... " button from your game's website to the https://accounts.trymetafab.com/oauth/?...
single sign-on flow. From there, your player can log in to your game using their Ecosystem-level profile. After successfully logging in, the player will be redirected to the redirectUri
you set in the configurable query parameters.
This redirect uri will have the authenticated player profile's accessToken
, walletDecryptKey
, and id
. For example, a redirect uri may be https://mygame.com/game
and the resulting redirect will become https://mygame.com/game#accessToken=PLAYER_ACCESS_TOKEN&walletDecryptKey=PLAYER_WALLET_DECRYPT_KEY&id=PLAYER_ID
. From here, your game's webpage logic can grab the player accessToken
, walletDecryptKey
and id
from the fragment (#) url parameters and perform any final login/authentication logic needed for your game. Profile accessToken
and walletDecryptKey
work the same as a standard player.
Embed Pattern
The embed pattern is intended for mobile apps, native games, or any non-web implementations.
For example, you may choose to build a mobile app or desktop game and an ecosystem's single sign-on for login.
You can use the embed pattern by excluding the redirectUri
from the single sign-on flow's query parameters. This allows you to do an in-app or in-game web browser/modal window that opens the target ecosystem single sign-on flow webpage. Your player would login to their ecosystem profile through this flow, grant your game the requested permissions, and once finished the player's accessToken
, walletDecryptKey
, and id
will be set and update the auth page's URL. An example final page URL after a player completes the flow may look like https://accounts.trymetafab.com/oauth/?ecosystem=b573c2dc-5e93-4c99-a57f-569480d05204&game=addd8995-50b3-4021-aa61-da7277432b9a
You can use a URL change listener for your in-app or in-game browser modal and wait for the #accessToken=
, walletDecryptKey=
&id=
fragment properties to be set on the URL. Once set, you can extract the player's accessToken
, walletDecryptKey
, and id
and perform any additional auth logic for your game from there and automatically close the browser modal/pop-up.
Updated 10 months ago