Authenticate Users

Fractal Login + Wallet

In order to authenticate users and be able to access their wallet, you need to do the following:

  1. Get an approval url and code using your Client Id.
  2. Redirect the user to sign in using the URL provided.
  3. Create a poller to check if the user has authenticated with your game.
  4. Success! You can now read user details and view their wallet.

Examples are provided as curl requests, but feel free to adapt them to whichever language you are using, such as Javascript, C#, C++, Rust, or Go.

You can test out our auth flow in our API reference starting at https://reference.fractal.is/reference/geturl (opens in a new tab)

1. Get approval URL with client id and scopes

You can do this step from the client directly, or you can proxy through your backend to do this.


Each API endpoint is protected by a certain scopes. When a user signs into a project, we tell tell them which scopes the project is requesting. If the authentication flow is not sent the correct scopes, following API calls will not work. Here is the list of available scopes (these are available as an enum in our web SDK):

  • identify (username/email/public keys)
  • items:read (NFTs and SFTs)
  • coins:read (fungible tokens)

How to get Approval URL

curl --request GET \
     --url 'https://auth-api.fractal.is/auth/v2/approval/geturl?clientId=<CLIENT_ID>&scope=items:read&scope=identify&scope=coins:read'

If successful your response will look like this:

  "code": "646ca818-2b48-4259-a8d0-9339e08c58a3",
  "url": "https://fractal.is/approve/v2/ede713085042ac6d4da27336149b38c0e5..."

This code will expire after 10 minutes

2. Redirect the user to the authentication URL

Now that you have the authentication url, you need to redirect your users to authenticate with Fractal.

The user will now go through the following flow:

  1. URL will open on Fractal's domain, and will prompt the user to Sign In with Fractal.
  2. They will be prompted to approve the game's authentication request.
  3. Once they click approve, they can go back to your game and the poller should now succeed and return an authentication token.

You're now ready to use the user's auth token to pull game-specific NFTs in their wallet or use the token to secure your api!

3. Check if user has signed in

You now need to check if the user has authenticated your game.

curl --request POST \
     --url 'https://auth-api.fractal.is/auth/v2/approval/result' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "clientId": "client_id",
     "code": "code"

Once the user has approved the authentication request on their side (Step 3), this will return an auth token and user_id as follows:

Sample response:

    "bearerToken": "eyJhbGciOiJS…slTm1GA",
    "userId": "{user_id}"

This token expires after 20 hours. It is scoped {user, project} and will allow you to access any of our SDK API calls on behalf of the user.