Authentication

Authentication is required for user data endpoints / actions in the form of a Wealthica user token.

API clients (both frontend and backend) will need to obtain a token before making user data API calls for or opening the Wealthica Connect Widget.

The token must be included in the Authorization: Bearer ${token} header in your Wealthica API request, or in the ?token= query string in the Wealthica Connect Widget URL.

The token is short-lived and you will need to obtain a new one when it expires.

info

Currently the default token lifetime is 1 hour (for API usage). However Wealthica Connect expects a fresh token and will expire the connect session once it's past 10 minutes since token iat.

Backend clients

The Wealthica user token can be requested by POSTing to {WEALTHICA_API_URL}/auth/token with:

• Your team's Client Id and Client Secret, which you get when signing up for Wealthica API. Passed as clientId & secret in request body JSON.
• The user's unique identification from your system (could be the username, id, or email). Passed as loginName in request header.

POST /auth/token HTTP/1.1
Host: api.wealthica.com
Content-Type: application/json
loginName: USERNAME_FROM_YOUR_SYSTEM

{
  "clientId": "YOUR_CLIENT_ID",
  "secret": "YOUR_CLIENT_SECRET"
}

The endpoint returns the following JSON:

{
  "token": "YOUR_USER_TOKEN"
}

Backend

const wealthica = Wealthica.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});

const user = wealthica.login('USERNAME_FROM_YOUR_SYSTEM');
const token = await user.getToken();

Shell

curl '{WEALTHICA_API_URL}/auth/token' \
  -X POST \
  -H 'loginName: USERNAME_FROM_YOUR_SYSTEM' \
  -H 'Content-Type: application/json' \
  -d '{
      "clientId": "YOUR_CLIENT_ID",
      "secret": "YOUR_CLIENT_SECRET"
  }'

Frontend client

Because the secret is required to obtain a user token, it will always need to be requested from your backend server which is supposed to store secret securely. Your frontend client will need to obtain a token via your backend server.

Your backend server could serve a /wealthica/token endpoint which authenticates and requests a user token on behalf of your frontend client.

Frontend

const wealthica = Wealthica.init({
  clientId: 'YOUR_CLIENT_ID',
  authEndpoint: '/wealthica/auth', // default value, your server should implement this endpoint
  auth: {
    params: { username: 'USERNAME_FROM_YOUR_SYSTEM' }
  }
});

const user = wealthica.login();
const token = await user.getToken();

Backend

const wealthica = Wealthica.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});

app.post('/wealthica/auth', async (req, res) => {
  // Replace with your own authentication
  const { username } = req.body;
  const user = wealthica.login(username);

  res.json({ token: await user.getToken() });
});

caution

secret must be securely stored and kept secret. You must never expose it in your frontend client (be it your website or mobile app).