Sign users up and in

This page shows how to use the Qoni SDK to let your app's users sign up and sign in through GenAuth's hosted page, and get their user ID and session (Access Token). Creating an Agent for the user, binding it to them and asking them to delegate access all start from here.

Draft design: hosted sign-in SDK

This page retains the target hosted sign-in design. npm 0.9.0 has no genauth.auth.createLoginUrl() or exchangeLoginCode(); type checking the design contract below does not make these methods executable. Use your existing GenAuth/OIDC sign-in integration to obtain a user ID and Access Token. The published package can read the user with currentUser() / genauth.userInfo(); see Qoni SDK.

Sign-up and sign-in both happen on Qoni's hosted page through the standard OIDC authorization code flow: your server only builds the redirect URL and exchanges the code, so the user's password never touches your server.

Before you start

• Node.js 20.11 or later.
• A Qoni AccessKey ID and Secret.
• A sign-in callback URL registered in your app settings in the Qoni Console, for example https://app.example.com/auth/qoni/callback.

Install the SDK and create the client on your app server:

npm install @qoniai/qoni

import { Qoni } from '@qoniai/qoni'

// Create the client on your app server only; never ship the AccessKey to a browser or phone
const qoni = new Qoni({
  accessKey: process.env.QONI_ACCESS_KEY!,
  secretKey: process.env.QONI_SECRET_KEY!,
})

1. Redirect to the hosted page

When the user taps "Sign up" or "Sign in", create the hosted page URL and redirect the browser to it:

const login = await qoni.genauth.auth.createLoginUrl({
  redirectUri: 'https://app.example.com/auth/qoni/callback',
  state: '<csrf-state>', // generated and stored by your app, checked on callback
  screen: 'signup', // open the sign-up screen for new users; pass 'login' for returning users
})
console.log(login.url) // redirect the browser to this URL

• redirectUri must exactly match the callback URL registered in the Console, or the hosted page refuses to send the user back.
• Your app generates state, keeps it in the user's session and checks it on callback to prevent cross-site request forgery.
• screen only decides which screen opens first; the user can switch between sign-up and sign-in on the hosted page.

2. Exchange the code on callback

After the user signs up or signs in, Qoni returns to redirectUri with code and state. Check state first, then exchange code for the user's identity:

const session = await qoni.genauth.auth.exchangeLoginCode({
  code: '<callback-code>',
  redirectUri: 'https://app.example.com/auth/qoni/callback',
})
const user = session.user // user.id is this user's ID in GenAuth
console.log(user.id, user.isNewUser, session.expiresIn)

• session.user.id is the user's ID in GenAuth; delegation and audit identify the user by it.
• session.accessToken represents the user's current session. Binding an Agent to the user requires it as proof that the user is present; see Personal Agent: bind the user and the Agent. Keep it with the user ID in your server-side session, and never send it to the browser.
• When user.isNewUser is true, the user just signed up, which is a good moment to guide them through first-time setup, such as creating their Agent.
• A code can be exchanged only once and expires quickly. If the exchange fails, send the user through step 1 again.

Checkpoint: you have user.id and session.accessToken, and state matches what you stored in step 1.

Next steps

• Read Personal Agent to create an Agent for a signed-in user, bind it, delegate access and let the Agent work for the user.
• Read Your first delegation in 30 minutes for the full delegation token flow.