Working With Fractal API
One of the main advantages of Fractal for developers is that all of the functionality is exposed via a simple REST API. You can interact with Fractal using any programming language, framework, or game engine.
If you wish to interact with our API directly, you can find the reference here (opens in a new tab) or jump into our Unity, Unreal or React SDK section of the documentation to get started with your favorite tooling.
To interact with our API directly or using our SDKs, you need API Keys that you can generate in the Fractal Studio.
Managing Your API Keys
Navigate to the "Integrations"
Navigate to the "Integrations" tab for your selected game in the Fractal Studio and click on "Generate your SDK Keys" to create a new Client Id and Secret.
List of Your API Keys
You can generate multiple API keys for different environments (blockchains), or game builds. It's up to you how you use them. On the left side, you can see the last time the key was used, so if the key hasn't been used for a long time, you can also delete it.
Configure API Key
Click on the pencil icon to modify the specific API key. For example, you can change the target blockchain, set whitelisted URIs or refresh the secret key if you suspect your account has been compromised.
Whitelisted URIs are only applicable to games running in the browsers. You can leave this list empty if your game runs on a desktop.
Ensure you have selected the right target chain. For example, if you are using Polygon, ensure you have selected Polygon as the target chain in the key settings, or you will be unable to access the user's Polygon wallet via a specific key.
Client and Server Authentication
You may have noticed that API keys have a client id and a client secret because there are two access patterns for Fractal APIs: queries on behalf of a project and queries on behalf of a user.
Never store your project secret or interact with server APIs in your game client. Doing so is a security risk and may result in your project being suspended from Fractal.
-
Project-based queries from a server, requests require client secret as well as a client id, which can be exchanged for a project API token. By project-based queries, we mean actions that are not interacting with the user's account, such as reporting scores to leaderboards, creating NFTs, etc.
-
User-based queries happen from clients (browsers, game clients, etc.). You can exchange the client id and user id for a user access token. You can access user-specific data via these queries, such as their wallet address, inventory, etc.
Both project API and user access tokens expire after 20 hours. Make sure you validate the token expiration and refresh it when needed on the server side.
The following is a basic structure of how Fractal APIs are integrated into your game:
For example, creating an authentication session only requires a client id since user access tokens are read-only scoped and don't return sensitive data. Also, this workflow is more convenient, especially if games do not have large server-side setups.
On the other hand, actions such as reporting scores to our leaderboards require an API secret (you do not want users posting their own scores!). And should be done from the game's server side.
Communication between your game client and the game server is up to you, but we recommend using secure protocols like HTTPS/WSS with proper authentication and different anti-cheat mechanisms.