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

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.

const response = await
    { headers: { Authorization: `Bearer ${<PORTAL_API_KEY>}` } }
const clientSessionToken =;
const clientId =;

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
    { headers: { Authorization: `Bearer ${<PORTAL_API_KEY>}` } }
const refreshedClientSessionToken =;

Your user can now use this refreshed clientSessionToken.

When your user's CST expires, all Portal SDKs will throw an error on the next MPC Operation the user makes (e.g. creating a wallet, backing up a wallet, recovering a wallet, or signing). That error will include the error code INVALID_API_KEY in the SDK methods, which you can use as an indicator to refresh your CST.

Last updated