You will have a browser page that signs a user up, signs them in, knows who is signed in when it loads, and signs them out, using the prebuilt client in cookie mode. Every snippet is a complete function from a file the build type-checks.
- A Go app serving the library's routes under
/auth. If you have none yet, Your first app builds one, andexamples/quickstartis the finished program (go run ./quickstartinexamples/, listening on port 8081). - How it works for what the client is. This page uses Way 1, the prebuilt client.
- "Same origin" means the page and
/authare served from one scheme, host and port. Either the Go app serves your built frontend, or your dev server proxies/authto the Go app. In the proxy case the browser'sOriginis the dev server's, so add it toauth.WithTrustedOriginsas SPA frontends › Step 2 shows; otherwise every sign-in answers403 auth.origin_not_trusted. A frontend on another site uses bearer mode instead.
Copy the five files of clients/ts/src into a folder of your frontend, for example src/auth/ (or pnpm add @ubgo/auth-client and import from @ubgo/auth-client instead of ./auth/index.ts):
cp path/to/ubgo/auth/clients/ts/src/*.ts src/auth/Make sure your tsconfig.json has "allowImportingTsExtensions": true and "moduleResolution": "bundler", because the files import each other with .ts paths. Do not edit the files; they are replaced as a whole when the library changes.
List the plugins your Go app wires. This one wires email and password, like examples/quickstart. The base URL is the path the Go app mounted the routes under; on the same origin, a path is enough, and the browser sends the session cookie by itself.
auth · clients/ts/examples/spa.ts:10-13
export const auth = createAuthClient({
baseURL: "/auth",
plugins: [email(), password()],
});Put this in one module (here spa.ts) and import auth everywhere else. Creating a client is cheap, but one shared client keeps the plugin list in one place.
password.signUp creates the user and, unless the server requires a verified address first (email.RequireVerified()), signs them in. Its answer tells the page which case it is in:
signUp · clients/ts/examples/spa.ts:18-23
export async function signUp(address: string, secret: string, name: string): Promise<string> {
const { data, error } = await auth.password.signUp({ identifier: address, password: secret, name });
if (error) return error.message;
if (data.verificationRequired) return "Check your inbox to verify your address.";
return `Welcome, ${data.user.name}.`;
}The editor knows the shape of data here (user, verificationRequired, secondFactorRequired) because it was generated from the Go struct the route returns. Hover over signUp to see the route and its requirement.
A plain DOM form; in React, Vue or Svelte you call the same method from your own submit handler.
wireSignInForm · clients/ts/examples/spa.ts:43-57
export function wireSignInForm(form: HTMLFormElement, status: HTMLElement): void {
form.addEventListener("submit", async (event) => {
event.preventDefault();
const fields = new FormData(form);
const { data, error } = await auth.password.signIn({
identifier: String(fields.get("email") ?? ""),
password: String(fields.get("password") ?? ""),
});
if (error) {
status.textContent = error.code === "password.invalid_credentials" ? "Wrong address or password." : error.message;
return;
}
status.textContent = `Signed in as ${data.user.name}.`;
});
}error.code is a closed union of every code the server can answer: "password.invalid_credentials" autocompletes, and a typo is a compile error. Errors covers the rest. A user with two-factor on gets secondFactorRequired: true instead of a full sign-in; Flows shows the second step.
session() is a core method, so it is on the root of the client, not under a plugin. A visitor who is not signed in gets auth.signed_out (401) as an error, never an exception:
currentUser · clients/ts/examples/spa.ts:28-32
export async function currentUser(): Promise<{ id: string; name: string } | null> {
const { data, error } = await auth.session();
if (error) return null;
return { id: data.user.id, name: data.user.name };
}Call it when the app starts and keep the result in whatever state your framework uses.
signOut · clients/ts/examples/spa.ts:36-38
export async function signOut(): Promise<void> {
await auth.signOut();
}The server ends the session and clears the cookie; the next session() answers auth.signed_out.
The repository's smoke run does Steps 3 to 6 against the real two-factor example, in cookie mode and then bearer mode. The cookie-mode half of a real run (AUTH_SMOKE_PORT=8096 task ts:smoke; it needs Node 22.18 or later):
cookie mode
ok password.signUp: {"user":{"id":"usr_6egpf7rjidthelsqd7awnxc5","name":"Smoke","image":""},"verificationRequired":false,"secondFactorRequired":false}
err password.signIn (wrong password): 401 password.invalid_credentials "The sign-in details are not right."
narrowed: error.code is the typed code password.invalid_credentials
ok password.signIn: {"user":{"id":"usr_6egpf7rjidthelsqd7awnxc5","name":"Smoke","image":""},"verificationRequired":false,"secondFactorRequired":false}
ok session: {"user":{"id":"usr_6egpf7rjidthelsqd7awnxc5","name":"Smoke","image":""},"expiresAt":"2026-10-19T06:02:30.637908Z"}
ok signOut: {"ok":true}
err session (signed out): 401 auth.signed_out "Sign in to continue."
Each ok line is a data, each err line an error with its status, code and message. To see the same in your own app, open the browser's network tab: every call is one request to /auth/..., a POST with a JSON body or a GET with a query string, and the session travels as the __Host-auth_session cookie, which the page's scripts cannot read.
- A dev server on another port answers
auth.origin_not_trusted(403). Vite on:5173in front of the Go app on:8081is two origins. Proxy/auththrough the dev server and trust its origin withauth.WithTrustedOrigins, as SPA frontends › Step 2 shows. The sign-in itself may succeed (it carries no cookie yet, unless the server also turned onauth.WithFetchMetadata) and only the next mutation fail, which makes this look like a sign-out bug. baseURLwithout the mount prefix."/"or"http://localhost:8081"sendsPOST /password/sign-in, which nothing serves. Depending on what answers the miss, the call resolves toauth.unknown_operationor, when your router's plain-text 404 answers,client.invalid_response. The base URL is the prefix the Go app mounted under,"/auth"here.- A red 401 in the console on every page load is normal.
session()for a visitor who is not signed in answersauth.signed_outwith status 401, and browsers log every 4xx. The client resolves it as an error, not an exception; Step 5'scurrentUserturns it intonull. verificationRequired: truemeans not signed in. Withemail.RequireVerified()on the server, sign-up creates the account and mails a link but issues no session, sosession()still answersauth.signed_outuntil the address is verified (Flows › Email verification).tsconfig.jsonwithoutallowImportingTsExtensions. The five files import each other as./runtime.ts; without that setting and"moduleResolution": "bundler",tscrefuses every import (An import path can only end with a '.ts' extension ...).- Editing the copied files. They are replaced as a whole on every upgrade or regeneration, so a local change disappears silently. Wrap the client in your own module instead (Step 2's
spa.tsis that module).
- Plugins: add
twofactor(),magiclink()or any other plugin your server wires. - Flows: email verification, password reset, magic links, OAuth buttons.
- Errors: your own messages per code.
- Your own plugins: when your Go app has operations of its own.