Web authentication methods

The methods on this page assume you have already created a client and are authenticating it. If you would rather have Portal identify your end users for you, with an email magic link, Google, or Apple, see Client Auth. Portal creates the client as part of the sign-in, so no server-side call is needed for a user’s first login.

Authenticating with a Client API Key

This approach requires the least setup, but is also the least secure as it exposes your Client API Key to your DOM. For this reason, we recommend that this method only be used during local development. The only thing required for this is to create a client like normal via the Portal REST API and use the clientApiKey for the apiKey option when initializing Portal.

import Portal from '@portal-hq/web'

const portal = new Portal({
    apiKey: 'YOUR_CLIENT_API_KEY',
    rpcConfig: {
      'eip155:1': 'YOUR-INFURA-OR-ALCHEMY-URL',
      'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': 'https://api.mainnet-beta.solana.com',
    },
})

Authenticating with a Web OTP

This approach is a bit more secure as it instead exposes a OTP to your DOM and once this is used, it’s invalidated on Portal’s end, which makes it unusable for authentication in the future. The steps required to accomplish this are:

Make a GET request to https://api.portalhq.io/api/v1/custodians/clients/${clientId}/web-otp using your CUSTODIAN_API_KEY as a Bearer token.
Initialize Portal with the delivered OTP as the authToken initialization option.

Fetching a Web OTP

// On your server
yourApp.get('/otp', (req: Request, res: Response) => {
  const url = `https://api.portalhq.io/api/v1/custodians/clients/${clientId}/web-otp`
  const { data } = await axios.get(url, {
    headers: {
      Authorization: `Bearer YOUR-CUSTODIAN-API-KEY`,
    },
  })

  res.send(data.otp)
})

Initializing Portal

import Portal from '@portal-hq/web'

const initializePortal = () => {
  const response = await fetch('https://yourserver.com/otp', {
    credentials: 'include'
  })

  const authToken = response.text()

  const portal = new Portal({
    authToken,
    rpcConfig: {
      'eip155:1': 'YOUR-INFURA-OR-ALCHEMY-URL',
      'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': 'https://api.mainnet-beta.solana.com',
    },
  })
}

Authenticating with an authUrl

This approach is by far the most secure as it never exposes any Portal credentials to your DOM. This works by adding a route to your application that fetches an OTP and redirects to Portal’s server for validation. The URL to your authentication route is then provided as the authUrl option when initializing Portal. The steps required to accomplish this are:

Create a route on your server that gets a new Web OTP and redirects to https://web.portalhq.io/clients/token/validate?otp=YOUR-WEB-OTP
Enable CORS access to https://web.portalhq.io on your new route
Initialize Portal with your authUrl

Creating an authentication route

// On your server
yourApp.get(
  '/portal/authenticate', // This can be any route you like
  cors({
    credentials: true,
    origin: 'https://web.portalhq.io',
  }),
  async (req: Request, res: Response) => {
    const url = `https://api.portalhq.io/api/v1/custodians/clients/${clientId}/web-otp`
    const { data } = await axios.get(url, {
      headers: {
        Authorization: 'Bearer YOUR-CUSTODIAN-API-KEY'
      }
    })

    // This redirect is where the magic happens
    res.redirect(`https://web.portalhq.io/clients/token/validate?otp=${data.otp}`)
  }
)

Initializing Portal with an authUrl

import Portal from '@portal-hq/web'

const portal = new Portal({
  // This URL corresponds to the route you created in the previous step
  authUrl: 'https://yourserver.com/portal/authenticate',
  rpcConfig: {
    'eip155:1': 'YOUR-INFURA-OR-ALCHEMY-URL',
    'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': 'https://api.mainnet-beta.solana.com',
  },
})

Authenticating with Client Auth

The three approaches above all assume a client already exists and your backend is authenticating it. With Client Auth, Portal identifies the end user and creates the client as part of the sign-in, so no backend call is needed at all. Instead of a credential, you pass a clientAuth configuration. Like the authUrl approach, this never exposes a Portal credential to your DOM — the resulting Client Session Token stays on the Portal origin — but unlike authUrl it needs no server-side route of your own.

import Portal from '@portal-hq/web'

const portal = new Portal({
  clientAuth: {
    authEnvironmentId: 'YOUR_AUTH_ENVIRONMENT_ID',
    redirectUrl: 'https://example.com/auth/callback',
  },
  rpcConfig: {
    'eip155:1': 'YOUR-INFURA-OR-ALCHEMY-URL',
    'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': 'https://api.mainnet-beta.solana.com',
  },
})

Sign-in is always explicit, and the SDK waits for it before becoming ready. See Client Auth for the full flow, including the callback route and session handling.

Getting Started

SDKs

APIs

Integrations

Resources

Web authentication methods

Authenticating with a Client API Key

Authenticating with a Web OTP

Fetching a Web OTP

Initializing Portal

Authenticating with an authUrl

Creating an authentication route

Initializing Portal with an authUrl

Authenticating with Client Auth

​Authenticating with a Client API Key

​Authenticating with a Web OTP

​Fetching a Web OTP

​Initializing Portal

​Authenticating with an authUrl

​Creating an authentication route

​Initializing Portal with an authUrl

​Authenticating with Client Auth

Authenticating with a Client API Key

Authenticating with a Web OTP

Fetching a Web OTP

Initializing Portal

Authenticating with an authUrl

Creating an authentication route

Initializing Portal with an authUrl

Authenticating with Client Auth