Hosted login
The hosted sign-in pages on signin.<domain>: the authorize redirect, the token exchange, languages, branding and security.
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:is the sign-in app your users see. Sign-in steps open at/ / signin. ohauthcat. com/ <environment> /, errors at<environment> ? flow=… ?error=…, password reset links at/and invitations at<environment> / reset#token=… /. It is also the passkey relying party ID, unless you choose a custom sign-in host (below).<environment> / invite#token=… https: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. ohauthcat. com /stay as a fallback.login/ <environment>
Custom sign-in domain
Section titled “Custom sign-in domain”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 /. Once verified, the sign-in pages are served on https: and it is accepted as a sign-in API origin (CORS on /), only for the environment that owns it. The hosted-login cookies and OAuth redirects stay on login.ohauthcat.com.
Choose the active sign-in host
Section titled “Choose the active sign-in host”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 /; change it with PUT /.
- Preview first.
GET /returnsv1/ environment/ signin_host? preview_hostname=login. example. com&preview_rp_id_scope=hostname rp_idandpasskeys_not_usable: how many existing end-user passkeys would not work on that host. Withoutpreview_hostname, the count is for the current host. - Typed confirmation. The
PUTbody is{"hostname": "login..example. com", "rp_id_scope": "hostname", "confirm": "login. example. com"} confirmmust equal the new host exactly (signin.ohauthcat.comwhenhostnameisnull, which switches back to the default); otherwise the request answersparameter_invalidonconfirm. In the dashboard you type the host yourself, and the change needs a recent second factor (step_up_required). The change is audited asenvironment..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. and ohauthcat environment signin-host set login.. 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.
RP ID scope
Section titled “RP ID scope”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, hereexample.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.
What happens to existing passkeys
Section titled “What happens to existing passkeys”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.
Native apps
Section titled “Native apps”If your iOS or Android app uses passkeys for this environment, add the active custom host to the app’s associated domains (webcredentials:) 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.
Start a sign-in
Section titled “Start a sign-in”Turn on the methods you want in methods (password, magic_code, passkey, social) with PUT /. Then redirect the browser to GET https: 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: 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: with the code_verifier. See sessions and tokens.
SSO by email domain
Section titled “SSO by email domain”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: and comes back to https:, 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>.
Require SSO for an organization
Section titled “Require SSO for an organization”Turn on sso_required with PUT / 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.
Sign out and revoke
Section titled “Sign out and revoke”POST https:revokes a refresh or access token (RFC 7009). Public browser clients call it without credentials./ / login. ohauthcat. com/ user_management/ revoke GETorPOST https:is OpenID RP-initiated logout: send/ / login. ohauthcat. com/ user_management/ logout id_token_hint(required) and, optionally, apost_logout_redirect_urithat is one of the environment’s registered redirect URIs, and astate. 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:lists these endpoints (/ / login. ohauthcat. com/ . well-known/ openid-configuration revocation_endpoint,end_session_endpoint) with the authorize, token and JWKS endpoints. Discovery is served on the login host only.
Hosted login API
Section titled “Hosted login API”The sign-in app calls a JSON API on the login host, under /: 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 answersflow_interrupted_retry. - Every
POSTsends theX-CSRF-Tokenheader with thecsrf_tokenof the last flow read. - Each answer is the next step, a
redirect_toor anerror. 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/resendemails 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 answerssign_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.
Account page
Section titled “Account page”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 mereturns the user, the organization, whether MFA is on and when they signed in. It never returns tokens. - Sessions:
GET sessionslists live sessions with a coarse device label, an optional location and the current one marked.POST sessions/ends a session and its refresh tokens; revoking the current one signs this browser out.{session}/ revoke - Connected apps:
GET grantslists the apps the user connected through the OAuth provider;POST grants/removes an app’s access.{grant}/ revoke - Factors:
GET factorslists passkeys, the authenticator app and the recovery codes left. Removing one withPOST factors/needs a sign-in in the last 10 minutes that passed a second factor ({factor}/ remove step_up_requiredotherwise). Removing the last factor while the environment or organization requires MFA answersuser_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, elsestep_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 devicelooks up the code a TV or CLI shows (RFC 8628) andPOST device/decideallows or denies it. Both decisions are recorded in your audit log.
Languages and branding
Section titled “Languages and branding”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).
Security
Section titled “Security”- 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.