Skip to main content
Portal can authenticate your end users for you. Instead of running your own login system and calling the Custodian API to mint a Client Session Token, you point your app at the Authentication API, the user signs in, and Portal hands your app a Client Session Token for that user’s client.

​
Sign-in methods

You choose which methods to enable, per environment. See Enable authentication.

​
What you need before you start

  1. Authentication turned on for the environment, with at least one method enabled.
  2. Your environment’s Auth Environment ID, from Authentication > Configure in the dashboard. Every request sends it in the x-portal-auth-environment-id header.
  3. At least one Redirect URL on the environment’s allow list. This is the page in your app that the sign-in returns the user to.

​
How authentication works

Every method follows the same three steps.
  1. Start the sign-in. Your app asks Portal to send a magic link, or asks for a provider authorize URL and opens it.
  2. The user comes back to your app. Portal redirects them to your Redirect URL with a single-use token query parameter appended.
  3. Exchange the token. Your app posts that token to Portal and receives a Client Session Token.
The token in step 2 is short-lived and single-use. If it expires or has already been exchanged, the user starts over.

​
Identify with an Auth Environment ID

The Authentication API is the one Portal API that does not take a Portal API Key or a Client Session Token. Instead, to communicate with the auth endpoints, you should use an AuthEnvironmentId (obtained from the dashboard):
The Auth Environment ID identifies an environment, it does not authenticate a caller. Treat it as public, the way you would an OAuth client ID. This is why Portal checks every magic link request against your Redirect URL allow list, your verified sending domains, and your own templates, and rate limits magic link sends per email address.

​
A complete sign-in

Here is how a magic link sign-in plays out end to end. Google and Apple follow the same shape, differing only in how the sign-in starts: instead of sending an email, your app sends the user to the provider to consent. Your app never sees the user’s password, because there isn’t one, and it never needs a server-side call to create the client. Portal creates the end user and their client during the exchange. Once your app holds the Client Session Token, it initializes a Portal SDK and carries on as it would with any other Portal client. If the environment requires two-factor authentication, one step is added between the exchange and the session: Portal returns a short-lived credential instead of the Client Session Token, and your app prompts for a code from the user’s authenticator app first. See Two-factor authentication. For the requests and responses behind each step, see Email magic links or the API reference.

​
Tokens in the flow

The first two are short-lived. Once either is used or expires, the user has to sign in again. The Client Session Token behaves the same as any other Portal CST, and refreshes itself on every authenticated request, so an active user’s session stays alive without extra calls. See Authentication and API Keys for the details. One difference is worth calling out. Normally, when a CST finally expires, your backend mints a replacement with your Portal API Key. With Portal-managed authentication the end user just signs in again, and that sign-in issues a fresh Client Session Token. No Portal API Key and no backend call are involved.

​
Wallet creation

The Auto-create wallet setting is reported back to your app by GET /auth/methods as autoCreateWallet. It is a signal for your app and the Portal SDKs, not something the Portal API acts on.

​
Gas sponsorship

Gas sponsorship lets your organization pay network fees on behalf of your end users, using the policies and chains you configure. See Account Abstraction. The flag that turns it on is named isAccountAbstracted, but what it controls is whether the client Portal creates uses gas sponsorship. Portal creates the end user’s client for you during the sign-in, so that choice is made when the sign-in starts, not when the token is exchanged. Pass isAccountAbstracted on the call that begins the flow: Query parameters are strings, so the OAuth call takes the literal true or false. Any other value is rejected with a 400. Portal carries the value through the rest of the flow for you. Neither the token exchange nor the two-factor step takes the parameter again. Sending true requires gas sponsorship to be enabled for your organization and configured for the environment. If either is missing, the call fails with a 400 rather than failing later at wallet creation:
The flag only takes effect when the client is created, on the user’s first sign-in. A returning user keeps the client they already have, and sending a different value on a later sign-in does not change it.

​
What comes back

A completed sign-in returns the client Portal resolved for the user, so your app never has to guess:
  • clientId, the ID of the user’s Portal client.
  • isAccountAbstracted, whether that client uses gas sponsorship.
Both are returned alongside clientSessionToken, whether the sign-in finished at the token exchange or after a two-factor code. They are the client’s actual values, which for a returning user may differ from what you sent.

​
How this compares to other Portal credentials

  • Portal API Key. Your server-side key, used against the Custodian API to create clients and mint session tokens yourself. Unchanged, and still the right choice if you already run your own login. See Authentication and API Keys.
  • Web OTP and authUrl. The existing way to authenticate a Web SDK user, where your backend requests a one-time password for a client it already created. See Web authentication methods.
  • Portal-managed authentication. What this section covers. Portal identifies the user and creates the client, so you do not need a login system or a server-side call for first sign-in.

​
Next steps

Enable authentication

Turn authentication on for an environment and configure its settings.

Email magic links

Verify a sending domain, build an email template, and send magic links.

Google OAuth

Create a Google OAuth client and connect it to Portal.

Apple OAuth

Set up Sign in with Apple and connect it to Portal.

API reference

Full reference for every Authentication API endpoint.