# Hosted login

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.

## Hosts

- `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.

### 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 /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`.

### 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 /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`](/errors/parameter_invalid/) on `confirm`. In the dashboard you type the host yourself, and the change needs a recent second factor ([`step_up_required`](/errors/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.

#### 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, 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.

#### 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

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.

## Start a sign-in

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](/user-management/sessions-and-tokens/).

## 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://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>`.

## Require SSO for an organization

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`](/errors/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

- `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.

## Hosted login API

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`](/errors/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`](/errors/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](/spec/login-v1.yaml) (OpenAPI 3.1). It has no API key scopes, so it is not part of the [API reference](/reference/api/).

## 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`](/errors/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](/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`](/errors/step_up_required/) otherwise). Removing the last factor while the environment or organization requires MFA answers [`user_last_factor`](/errors/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`](/errors/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.

## 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](/hosted-portal/branding/) (logo, colors, favicon and font on Pro and above).

## 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.
