How to OAuth

Depending on your usage, you can implement this with pop-up window or redirection

Popup window method

Add a message event listener like the following

window.addEventListener('message', async function(event) {
    console.log(event)
    // Check for the user data in the message
    if (event.data?.type === 'well-oauth-token' && event.data?.token) {
        // verify and store the token in a secure way
        const jwtToken = event.data?.token;
        // Close the popup window
        if (popup) {
            popup.close();
        }
    }
});

Redirect method

Set location.href

location.href = `https://api.well.eco/oauth/auth?state=${randomString()}${Math.floor(Math.random() * 100000)}&redirect_url=${encodeURIComponent(yourURL)}`;

If the oauth success, the token will be included as the search param to the redirect_url provided.

You can get the redirect token with the following code:

const initialToken = new URLSearchParams(location.search).get('token');

After getting the token, you can request the user information with the following API

Fetch with token

GET https://api.well.eco/oauth/me

Headers

Name	Value
Content-Type	application/json
oauth-token	{jwt_token_you_get}

Body(JSON

Name	Type	Description
id	string	id of the user
linkedAddress	string	linked ETH address
token	Object	Type as below

{
  "description": string,
  "image": string,
  "tokenId": string,
  "name": string,
  "attributes": [
    {
      "trait_type": string,
      "value": string
    }
  ],
  "createdAt": string
}

Response

200

{
  "id": "nX9d7H3cPQWmxrK2t3jh4UzIcGo5",
  "linkedAddress": "0x3F8B9a45678dCd872e93Be582f54AFe912b874Dc",
  "token": {
    "description": "Hello test.well, Well ID is the digital identity representing you in the ever growing network of wellness. Powered by WELL3.",
    "image": "https://s3.well3.com/WellID/7752/1.jpg",
    "tokenId": "77522218045247854526172210698749283758228288462773800836215567039694054862682",
    "name": "test.well",
    "attributes": [
      {
        "trait_type": "Type",
        "value": "Well ID"
      }
    ],
    "createdAt": "1713175672123"
  }
}

400

Telegram mini app oauth

1. Use the update account API to update your "tgResultCallbackURL", "tgBotID", "tgBotMiniAppURL"

2. Add the following code to your link/login well3 button callback

window.open(`https://api.well.eco/oauth/tg-mini-app?oauth_app_id=${YOUR_WELL_APP_ID}`, '_blank');

1. Receive the result callback in your backend. The request will be a GET request, with a jwt attached to the API query. Nodejs example code:

import jwt from 'jsonwebtoken';
router.get('/tg-well-oauth-callback', async (req, res, next) => {
  const decoded = jwt.verify(req.query.jwt, WELL_OAUTH_PROJECT_SECRET);
  const {tgUserID, token} = decoded;
  // Code to bind the user in your server with the access token
  await redis.set(`tg-test:${tgUserID}`, token);
  res.send();
});

1. Our telegram bot will have a button to redirect the user back to your telegram mini app with the tgBotMiniAppURL you provided, so it is important to fill in the URL.

2. When the user go back to your bot, fetch the access token stored in your server to get the Well user info.