# Your first hosted login

Connect a small server application to Oathvera, sign in on your hosted page, and return to a working callback. Start here when your product has a backend that can keep a client secret.

**Time target: 5–10 minutes after the prerequisites are ready.** This is a first-login target, not a measured guarantee or an estimate for migrating a production product. You need Node.js 22 or newer, the downloadable reference bundle, access to a ready Sandbox workspace, and permission to create an application. There is no published Oathvera SDK to install today; this guide uses the included reference application.

## 1. Register the application

In the Oathvera dashboard, select **Sandbox**, then **Applications → Create application**.

1. Name your product and select **Server web application**.
2. Register this callback exactly: `http://localhost:3000/callback`.
3. Inherit the workspace's enabled sign-in methods. For a simple individual-user integration, choose the corresponding **Login Experience**; organization-only admission requires a membership setup too.
4. Finish creation and securely save the one-time client secret. In **Quickstart**, select this client and copy its complete issuer and client ID.

Use one enabled, configured method for the first login. Password signup must be allowed if you plan to create an account; email-based verification needs working delivery. Your dashboard administrator account is separate from the application's end-user account. If a required method is unavailable, configure it under workspace **Authentication** before continuing.

You can leave API resources, roles, social providers and custom domains for later. Basic user sign-in does not require an API grant. Use the generated authentication hostname initially.

**Checkpoint:** you have an issuer, a client ID starting with `cli_`, a server secret and the exact callback. The application ID starting with `app_` is not the client ID.

## 2. Configure the local reference

Download the [Node.js reference bundle](https://developer.oathvera.com/downloads/oathvera-examples-0.5.0.zip), unzip it, and open a terminal in the folder containing the extracted `oathvera-examples` directory:

```sh
cd oathvera-examples
npm ci --ignore-scripts
cp .env.example .env
```

Edit `.env` in your editor. Copy your own issuer, client ID and secret over the placeholders; keep these settings for this first check:

```dotenv
OATHVERA_REDIRECT_URI=http://localhost:3000/callback
OATHVERA_SCOPE=openid
OATHVERA_RESOURCE=
```

The full issuer includes `/t/ten_…`. Keep its hostname and path intact, with no trailing slash. `.env` is ignored by Git. Never put a server secret in frontend configuration such as a `VITE_` or `NEXT_PUBLIC_` variable.

## 3. Sign in

```sh
npm run web
```

Open [the local login route](http://localhost:3000/login). It redirects to your Oathvera hosted login. Sign in with an application user or create an account if registration is enabled, and complete any required verification or MFA. A successful callback displays **Signed in successfully** at `http://localhost:3000/account`.

**Checkpoint:** the browser returns to the local application, its server validates the ID token, and a new HttpOnly application-session cookie is issued. Tokens stay on the server. A successful dashboard **Try preview** does not satisfy this checkpoint: Try is an appearance preview.

Select **Log out** on the sample's account page. The sample revokes its grant and clears its local session. This demonstrates application logout, not global or upstream-provider logout. Stop the server when finished.

## 4. Add the identity fields your product needs

The initial `openid` scope is enough to establish identity. If your product needs a verified email and optional display name, confirm these scopes are registered for the client, set the following value, restart the sample and begin a fresh login:

```dotenv
OATHVERA_SCOPE=openid profile email
```

Your product should verify scoped claims as described in [adding login to your application](https://developer.oathvera.com/guides/add-to-your-app/#identity-and-profile). `email_verified` must be the boolean `true` when verified email is required; requesting the scope does not itself verify the address. A display name is optional. The reference's success screen deliberately does not print claims or tokens.

## 5. Bring the flow into your product

Use [the application integration guide](https://developer.oathvera.com/guides/add-to-your-app/) for direct hosted entry, callback handling, account mapping and current-session checks. Use [the production handoff](https://developer.oathvera.com/guides/production-handoff/) before moving customer traffic.

The reference is a local protocol demonstration. Its session store is in memory, it has no refresh implementation or ongoing online session check, and it fetches discovery at startup. It is not a production session middleware package. These boundaries and the precise protocol are covered in the [server-web guide](https://developer.oathvera.com/quickstarts/server-web/).

If a checkpoint fails, start with [troubleshooting](https://developer.oathvera.com/troubleshooting/). Fix the first failing stage before changing credentials, domains or infrastructure.