🔑Authentication

This guide will walk you through all of the credentials you need to access Portal.

Portal API Authentication

There are two classes of authentication used with Portal.

Portal API key

The API key used by your server to make requests to Portal.

Getting a Portal API key

Reach out to us on Slack to get access to the web app!

Log in and create a Portal API Key at app.portalhq.io.

Before going live with real users, always ensure that you create clients using a Portal API Key from your Portal's Production environment. Read more here on going live with real users.

Client Session Token

Users are required to authenticate their devices to Portal in order to create wallets and submit transactions. Client Session Tokens (CST) are short-lived, auto-refreshing tokens used to authenticate users to Portal.

Short-Lived CSTs expire after 24 hours of no activity. After this, a new CST must be requested from your backend.

Auto-Refreshing Every authenticated request with a CST updates the token's expiry to 24 hours from that request time. There's a max refresh duration of 7 days, after which a CST can no longer be auto-refreshed.

The goal of this system is keep sessions short (reducing attack windows) while minimizing the number of requests needed to create sessions.

In Practice:

• Active User: If a user uses Portal daily, their CST expiry extends by 24 hours each day. They'll need a new CST from your backend only once per week (after hitting the 7-day max refresh duration).

• Inactive User: Users logging in after a few days or weeks will need a new CST from your backend on every login since CSTs expire after 24 hours.

Server implementation

To authenticate mobile users with Portal, they need a unique Client Session Token. Request this token from your backend using the Portal API Key, then share it with mobile users after they log in.

Initial Registration

When a user first registers for your mobile app, use your Portal API Key to create a Client Session Token. Remember to associate the returned clientId with the user in your system.

portal.ts

const response = await axios.post(
    `https://api.portalhq.io/api/v1/custodians/clients`,
    {}, 
    { headers: { Authorization: `Bearer ${<PORTAL_API_KEY>}` } }
);
const clientSessionToken = response.data.clientSessionToken;
const clientId = response.data.id;

Ensure the clientId is stored securely as it is crucial for future operations.

Subsequent Logins

When the token needs refreshing (during later logins), use the following endpoint:

const response = await axios.post(
    `https://api.portalhq.io/api/v1/custodians/clients/${clientId}/session`,
    {}, 
    { headers: { Authorization: `Bearer ${<PORTAL_API_KEY>}` } }
);
const refreshedClientSessionToken = response.data.clientSessionToken;

Your user can now use this refreshed clientSessionToken.

npm Authentication

In order to use Portal's npm packages, you need to get an authToken for use in your .npmrc file.

Reach out to Portal on Slack to get an authToken

Using the authToken

Create an .npmrc file, if you do not already have one, at the root of your app. Using the npm authToken you received from us to configure permissions to install the module.

.npmrc

@portal-hq:registry=https://registry.npmjs.org
//registry.npmjs.org/:_authToken=<NPMTOKEN>

After collecting your credentials, you are ready to instantiate the Portal component in your app. Head back to Installation to install.