Skip to content
Dashboard
Theme
Theme

Hosted login

The hosted sign-in pages on signin.<domain>: the authorize redirect, the token exchange, languages, branding and security.

View Markdown

The hosted login is a set of pages OhAuthCat serves for your end users: sign-in, sign-up, password reset, email verification, MFA enrolment, invitation acceptance, an organization switcher and an account page where users manage passkeys, authenticator apps and connected apps.

  • https://signin.ohauthcat.com/<environment> is the sign-in app your users see. Sign-in steps open at /<environment>?flow=…, errors at ?error=…, password reset links at /<environment>/reset#token=… and invitations at /<environment>/invite#token=…. It is also the passkey relying party ID, unless you choose a custom sign-in host (below).
  • https://login.ohauthcat.com is the API behind it: the authorize, token, revocation and logout endpoints, the JWKS, the OpenID discovery document and the issuer of end-user tokens. The server-rendered pages under /login/<environment> stay as a fallback.

On Pro and above you can add a custom domain of type signin (for example login.example.com) with POST /v1/custom_domains, then add the DNS records it returns and verify it with POST /v1/custom_domains/{custom_domain}/verify. Once verified, the sign-in pages are served on https://<your hostname> and it is accepted as a sign-in API origin (CORS on /login/<environment>/api/*), only for the environment that owns it. The hosted-login cookies and OAuth redirects stay on login.ohauthcat.com.

Each environment has one active sign-in host: signin.ohauthcat.com by default, or one of its verified signin hostnames. The active host is the WebAuthn relying party ID (RP ID) that new end-user passkeys bind to. Read it with GET /v1/environment/signin_host; change it with PUT /v1/environment/signin_host.

  • Preview first. GET /v1/environment/signin_host?preview_hostname=login.example.com&preview_rp_id_scope=hostname returns rp_id and passkeys_not_usable: how many existing end-user passkeys would not work on that host. Without preview_hostname, the count is for the current host.
  • Typed confirmation. The PUT body is {"hostname": "login.example.com", "rp_id_scope": "hostname", "confirm": "login.example.com"}. confirm must equal the new host exactly (signin.ohauthcat.com when hostname is null, which switches back to the default); otherwise the request answers parameter_invalid on confirm. In the dashboard you type the host yourself, and the change needs a recent second factor (step_up_required). The change is audited as environment.signin_host_changed.
  • Fallback. Deleting the hostname, or losing its verification, falls back to signin.ohauthcat.com.

From a terminal: ohauthcat environment signin-host get --preview login.example.com and ohauthcat environment signin-host set login.example.com --confirm login.example.com. In Terraform: the ohauthcat_environment_signin_host resource, which needs acknowledge_passkey_reset = true to apply a change and warns at plan time how many passkeys will not work.

  • hostname (default): passkeys bind to the hostname itself (login.example.com) and work only there. This is the narrowest choice.
  • registrable_domain: passkeys bind to the registrable domain (eTLD+1, here example.com), so they also work on your other subdomains. Every subdomain of that domain can then also request them, so choose it only when you control all of them.

A passkey is bound to the relying party it was created under and never moves. After a change, existing passkeys keep working only on the host they were created on (passkeys created before you chose a custom host keep working on signin.ohauthcat.com). On the new host they are not offered and not accepted; affected users sign in with another method and add a new passkey from the account page. passkeys_not_usable tells you how many users this affects before you switch.

If your iOS or Android app uses passkeys for this environment, add the active custom host to the app’s associated domains (webcredentials:login.example.com) and to the Android Digital Asset Links of the app (android_apps in the user management settings), the same way you added signin.ohauthcat.com. Passkeys created in the app after the change bind to the custom host.

Turn on the methods you want in methods (password, magic_code, passkey, social) with PUT /v1/user_management/settings. Then redirect the browser to GET https://login.ohauthcat.com/user_management/authorize with:

Parameter Meaning
client_id The environment’s publishable key (pk_…).
redirect_uri Must match a registered redirect URI exactly.
response_type code.
code_challenge The S256 PKCE challenge. Required on every request.
code_challenge_method S256.
state Your value, returned unchanged. Check it on return.
nonce Optional; copied into the ID token.
organization_id Optional; sign the user into this organization and apply its sign-in method rules.
prompt Optional; none signs in silently or answers at your redirect URI.

With prompt=none, a browser without a live hosted session returns to your redirect URI with error=login_required, or interaction_required when a step such as MFA or consent is needed. Every authorization response carries iss (RFC 9207); check that it is https://login.ohauthcat.com before you exchange the code.

The code that comes back lasts 60 seconds, is single-use and is bound to the client, the redirect URI and the PKCE challenge. Exchange it at POST https://login.ohauthcat.com/user_management/token with the code_verifier. See sessions and tokens.

When the environment enables the sso method and a sign-in starts with your publishable key, the identify step checks the email’s domain. If it is a verified domain of an organization (exactly, or a parent domain that includes subdomains) with an active, tested SSO connection of its own or shared with it, the user goes straight to that identity provider through https://auth.ohauthcat.com/sso/authorize and comes back to https://login.ohauthcat.com/login/<environment>/sso/callback, which finishes the sign-in. Any other email continues to the password or magic code step, and the answer looks the same either way, so the step never reveals which domains use SSO. An SSO failure returns to the sign-in app as ?error=<code>.

Turn on sso_required with PUT /v1/organizations/{org}/user_management_settings to make SSO the only way in for that organization’s users. When it is on, an email on one of the organization’s verified domains is sent to SSO as above, and every other first factor (password, magic code, passkey, social sign-in, sign-up and headless passkey sessions) answers end_user_sso_required (403). If SSO cannot be reached for that email (no active, tested connection), the identify step answers the same error rather than falling back to a password. Organizations without the policy behave exactly as before, so the response still never reveals which domains use SSO. A social sign-in that would create a new user for such a domain is refused before a session is issued.

  • POST https://login.ohauthcat.com/user_management/revoke revokes a refresh or access token (RFC 7009). Public browser clients call it without credentials.
  • GET or POST https://login.ohauthcat.com/user_management/logout is OpenID RP-initiated logout: send id_token_hint (required) and, optionally, a post_logout_redirect_uri that is one of the environment’s registered redirect URIs, and a state. It ends the hosted session and with it every refresh token of that session, then returns to that URI or to the sign-in app. An expired ID token is accepted as the hint.
  • GET https://login.ohauthcat.com/.well-known/openid-configuration lists these endpoints (revocation_endpoint, end_session_endpoint) with the authorize, token and JWKS endpoints. Discovery is served on the login host only.

The sign-in app calls a JSON API on the login host, under /login/<environment>/api/: GET flow reads the current step, and each step (identify, password, magic code, passkey, sign-up, email verification, password reset, MFA, organization choice, invitation, consent, bot challenge, sign-out) is a POST. You do not need it to add sign-in to your app; it is documented for teams that build their own sign-in screens on the login host’s rules.

  • A flow (flw_…) is bound to the browser that first reads it through an HttpOnly cookie. Another browser answers flow_interrupted_retry.
  • Every POST sends the X-CSRF-Token header with the csrf_token of the last flow read.
  • Each answer is the next step, a redirect_to or an error. Bot protection, rate limits and audit are the same as on the hosted pages.
  • On the email verification step after a sign-up, POST sign_up/resend emails a new code and invalidates the previous one. The user keeps the password and names they entered, and verifying still returns to your app. New codes are rate limited like other email codes: too soon or too often, the answer looks the same but no email goes out. A flow with no sign-up waiting for a code answers sign_up_not_pending (409).
  • Cross-origin calls are accepted only from the sign-in app’s origin, with credentials. The token and revocation endpoints also accept public browser clients without credentials, from the sign-in app or an origin of one of the environment’s registered redirect URIs.

The contract is the hosted login API document (OpenAPI 3.1). It has no API key scopes, so it is not part of the API reference.

The account page on the sign-in app uses the same JSON API, with the user’s hosted session for the environment. Without one, it answers login_required. A user can only see and change their own data; any other ID answers resource_not_found.

  • Profile: GET me returns the user, the organization, whether MFA is on and when they signed in. It never returns tokens.
  • Sessions: GET sessions lists live sessions with a coarse device label, an optional location and the current one marked. POST sessions/{session}/revoke ends a session and its refresh tokens; revoking the current one signs this browser out.
  • Connected apps: GET grants lists the apps the user connected through the OAuth provider; POST grants/{grant}/revoke removes an app’s access.
  • Factors: GET factors lists passkeys, the authenticator app and the recovery codes left. Removing one with POST factors/{factor}/remove needs a sign-in in the last 10 minutes that passed a second factor (step_up_required otherwise). Removing the last factor while the environment or organization requires MFA answers user_last_factor. New factors are added with the passkey and authenticator app steps; a first factor shows recovery codes once. A user who already holds a factor can add another only under the same rule as removing one: a sign-in in the last 10 minutes that passed a second factor, else step_up_required. The account page then asks them to sign in again. A user who has no factor yet can add their first from any signed-in session. After a factor is added or removed, the user’s other sessions are signed out.
  • Device sign-in: POST device looks up the code a TV or CLI shows (RFC 8628) and POST device/decide allows or denies it. Both decisions are recorded in your audit log.

The pages are available in English, German, Spanish, French, Japanese and Brazilian Portuguese, chosen from the browser’s language. They use your environment’s branding (logo, colors, favicon and font on Pro and above).

  • Every form POST carries a CSRF token compared with a __Host- cookie; pages send a strict Content Security Policy.
  • A new hosted session ID is issued after every authentication step, so a session cannot be fixed in advance.
  • Answers for sign-in, sign-up, email codes, password reset and invitations look the same whether or not the address has an account.
  • Rate limits use the client address resolved at the edge, never a forwarded header the client controls.