Fractal Authentication (v2)

If you are searching for a older version of the authentication flow, please refer to the v1 docs.

💡

We recommend to use the Fractal SDK to handle authentication. Use this guide only if you want to implement the authentication flow yourself. SDK interacts with the Fractal Launcher for smoother user experience.

Authentication Flow

In order to authenticate users and access their Fractal account both on the web and in-game, you need to do the following 3 steps:

Get an approval url and code.
Redirect the user to sign in using the URL provided.
Create a poller to check if the user has authenticated with your game.

Fractal account comes with a blockchain wallet, so you can use the authentication token to access the wallet's NFTs, coins and generate signing requests for on-chain transactions.

1. Get Approval URL and Code

Authentication requires a code challenge to be sent with the request. The code challenge is a Base64-encoded string of the SHA256 hash of the randomly generated code verifier.

To get an approval URL, you need to send a request to the /auth/signin_v2/authorize (opens in a new tab) POST endpoint. The body of the request should contain the JSON object with the following attributes:

Atribute	Content
`clientId`	Your game's client id.
`scopes`	Array of scopes you want to request (see below).
`codeChallenge`	Base64-encoded string of the SHA256 hash of the code verifier.

💡

Make sure the Base64 string of the code challange is URL-safe. Read more about URL safe Base64 encoding here (opens in a new tab).

Authentication Scopes

With authentication scopes you can control what features your game can access from the users' account.

Scope	Features
identify	Read user e-mail, id and blockchain wallet public key.
coins:read	Read tokens amount that are stored in the account.
items:read	Read items that are stored in the wallet.

Example

curl --request POST \
     --url https://auth-api.fractal.is/auth/signin_v2/authorize \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
    "scopes": [
        "<SCOPES>"
    ],
    "clientId": "<CLIENT_ID>",
    "codeChallenge": "<CODE_CHALLENGE_BASE64>"
    }'

Response

Atribute	Content
`approvalUrl`	The URL that you need to redirect the user to.

{
  "approvalUrl": "https://fractal.is/approve/v2/ede713085042ac6d4da27336149b38c0e5..."
}

Redirect user to the URL provided in the response, and save up the code for verification. Keep in mind that the URL will expire after 10 minutes.

2. Redirect to URL

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

💡

Open the authentication URL in a new tab, so that the user can easily go back to your game once they approve the authentication request. If the game is a desktop build, you can open the URL in the default browser.

The user will go through the following flow:

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

3. Verify Authentication

💡

Avoid spamming the verification endpoint with requests. We recommend to set up a poller that checks if the user has signed in every 5 seconds or when user returns to the game.

To check if the user has signed in, you need to send a request to the /auth/signin_v2/token (opens in a new tab) POSTendpoint. The request body should contain a JSON with the following attributes:

Atribute	Content
`verifier`	Base64 of the code verifier you used as a source for the code challenge.

Example

curl --request POST \
     --url https://auth-api.fractal.is/auth/signin_v2/token \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "verifier": "<CODE_VERIFIER_BASE64>"
    }'

Response

Once the user has approved the authentication request on their side, this endpoint will return JSON with the following attributes:

Atribute	Content
bearerToken	A token that you can use to access our SDK API calls on behalf of the user.
refreshToken	A token that you can use to refresh the bearer token.
userId	The user's Fractal id.

{
    "bearerToken": "<BEARER_TOKEN>",
    "refreshToken": "<REFRESH_TOKEN>",
    "userId": "<USER_ID>"
}

💡

This token expires after 20 hours. It is scoped to specific project and user.

Refreshing Token

To refresh the bearer token, you need to send a request to the /auth/signin_v2/refresh (opens in a new tab) POSTendpoint. The request body should contain a JSON with the following attributes:

Atribute	Content
`refreshToken`	A refresh token for the user.

Example

curl --request POST \
     --url https://auth-api.fractal.is/auth/signin_v2/refresh \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
    {
        "refreshToken": "<REFRESH_TOKEN>"
    }'

Response

If the refresh token is valid, this endpoint will return JSON with the following attributes:

Atribute	Content
bearerToken	A new token that you can use to access our SDK API calls on behalf of the user.

{
    "bearerToken": "<BEARER_TOKEN>",
    "refreshToken": "<REFRESH_TOKEN>",
    "userId": "<USER_ID>"
}

Authenticate Players Read Wallets