Fractal Authentication (v1)

🚫

Deprecated. Please use the Fractal Login v2 method instead.

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

To get an approval URL, you need to send a request to the /approval/geturl (opens in a new tab) GET endpoint. The URL query parameters are required as follows:

Atribute	Content
`clientId`	Your game's client id.
`scope`	Array of scopes you want to request (see below).
`redirectUri`	The URL that the user will be redirected to after they approve the authentication request. This URL must be whitelisted in your game's settings.

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 NFT items that are stored in the wallet.

Example

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

Response

Atribute	Content
`code`	A unique code that you can use to check if the user has approved the request.
`url`	The URL that you need to redirect the user to.

{
  "code": "646ca818-2b48-4259-a8d0-9339e08c58a3",
  "url": "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

💡

Call this verification endpoint every ~2 seconds until you get a successful response or request times out. We offer a separate endpoint to check if the user has signed in, so that you don't have to implement any complex logic or deeplinking.

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

Atribute	Content
`clientId`	Your game's client id.
`code`	The code you got from the approval URL (Step 1).

Example

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>"
     }'

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.
userId	The user's Fractal id.

{
    "bearerToken": "eyJhbGciOiJS…slTm1GA",
    "userId": "<USER_ID>"
}

💡

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

Authenticate Players Read Wallets