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, unzip it, and open a terminal in the folder containing the extracted oathvera-examples directory:

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:

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

npm run web

Open the local login route. 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:

OATHVERA_SCOPE=openid profile email

Your product should verify scoped claims as described in adding login to your application. 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 for direct hosted entry, callback handling, account mapping and current-session checks. Use the 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.

If a checkpoint fails, start with troubleshooting. Fix the first failing stage before changing credentials, domains or infrastructure.