Account portal

Authdog hosts the sign-in, sign-up, MFA, and account screens, so you can ship authentication without building that UI. The portal lives on the Authdog identity host, and you theme it per environment.

What the portal covers

The hosted Account Portal is the set of screens you would otherwise build yourself:

• Sign-in: email/password, social login, and enterprise SSO, depending on the connections enabled for the environment.
• Sign-up: self-service registration with whatever verification your environment requires.
• MFA: enrollment and step-up challenges (e.g. TOTP), presented automatically when a user or policy requires it.
• Account management: profile, credentials, linked sign-in identities, active sessions, and a Connected apps tab where users revoke OAuth clients they previously authorized.
• Account linking: the Connected accounts card on the Profile tab lists every sign-in identity attached to the account and offers one-click Link buttons for the environment's enabled social connections. A user invited by email can link their Google (or GitHub, Microsoft, Apple, ...) account and sign in with either method from then on.

Because the screens are hosted, they follow the connections and policies on the environment. You don't redeploy your app when you add a social provider or turn on MFA.

How account linking works

1. The user clicks Link Google in the portal. The browser performs a normal OAuth sign-in against that connection with mode=link in the OAuth state.
2. On callback, Authdog resolves the currently signed-in user from the session cookie. It doesn't issue a new session, and it doesn't create a user.
3. The link is accepted only when the provider returns an email that matches one of the account's emails (case-insensitive) and the provider does not report it as unverified. Mismatches, missing emails, and subjects already linked to another user are refused and explained back in the portal.
4. The identity is stored in users_identities. From then on, signing in with that provider resolves to the linked user, with the user's original subject (sub) preserved in tokens.
5. Unlink soft-detaches the identity. It is refused when it is the user's only credential (no password and no other identity). A detached provider account cannot sign the user in again until it is re-linked from the portal.

Each link and unlink emits a USER_IDENTITY_LINKED / USER_IDENTITY_UNLINKED audit event, and the console shows the identities on the user's Profile tab (read-only).

Theming per environment

Each environment (dev, staging, production) themes its portal independently: logo, colors, and copy. This means your development portal can look distinct from production while sharing the same flows, and you promote theming along with the rest of your environment config. See Deployments for how per-environment configuration is promoted.

How the redirect flow works

The portal uses a redirect-based flow:

1. Your app sends the user to the hosted portal on the Authdog identity host.
2. The user authenticates there (sign-in, sign-up, MFA as needed).
3. Authdog redirects the user back to your app, establishing an authdog-session cookie for the environment.
4. Your frontend and backend read that session and validate it against the environment's public key (pk_...).

Your application never handles raw credentials; it only ever sees the resulting session. See Sessions & tokens for how the session is validated on subsequent requests.

When to use the portal

Reach for the Account Portal when you want auth working with the least code and are happy to send users to an Authdog-hosted URL. Choose an alternative when you need auth inside your own layout:

• Components: prebuilt, themeable UI mounted directly in your app, no redirect.
• Custom flows: fully headless control when neither the portal nor components fit.

To get a portal working end to end, follow the Quickstarts.