Implement

Download a starter and integrate it with your web application.

1 · Plan URL, DNS, profile — register in the Console. 2 · Lab Try the reference web and mobile apps. 3 · Understand Embed styles, sign-in flow, server checks.

4 · Implement Starters, server routes, page stack, CSS.

Starter packages

Pick your server language. Each zip implements a minimal Kie.la authentication integration.

Node.js + Express Node.js + Express + SQLite Node.js hybrid (classic + Kie.la) Python + Flask PHP Go Java + Spark C# + ASP.NET Core Ruby + Sinatra Rust + Axum

There is also a native Android client integration.

Android

On your server

Use Node.js + Express as the reference. File names and the walkthrough below match Node.js with Express (see the lab application). The contract is not tied to JavaScript: any backend that exposes the same four /api/* routes, builds the same embed URLs, and talks to the authentication server the same way will work with the same client code kie-la-auth.js in the browser.

Node.js + Express reference

.env — APP_ORIGIN, optional auth URL and cookie settings
lib/env.js — load .env; resolve port, origin, auth URL
lib/embed-url.js — build iframe URL (authUi → login page path)
lib/auth.js — session exchange with the auth service
lib/tls.js — HTTPS client toward the auth server
service.js — routes below (+ static files)

You can skip /api/session. You can choose to manage the session yourself.

Server files

File	Role	Key points
`.env`	Your public origin and local settings.	`APP_ORIGIN` must match the URL registered in the Console. Optional: `KAUTHENT_URL` (default `https://auth.kie.la`), `PORT`, `BIND_HOST`, `COOKIE_SECURE`, `SESSION_COOKIE`, `SESSION_TTL_SEC`.
`lib/env.js`	Load `.env` and resolve startup settings.	Reads the file without overriding variables already set in the environment. Defaults: origin `http://localhost:3000`, auth server `https://auth.kie.la`. Cookie is marked Secure when the origin is `https`.
`lib/embed-url.js`	Build the iframe URL server-side.	Maps `authUi` (`header`, `minimal`, `large`, `rounded`) to the matching auth server path (`/login-header`, `/login-min`, `/login`, `/login-rounded`). Appends `embed=1` and `parent`.
`lib/auth.js`	Talk to the auth server; manage your session cookie.	`createAuth()` exchanges the iframe handoff token for a session id, reads `/api/me` on the auth server, and sets an HttpOnly cookie on your domain.
`lib/tls.js`	HTTPS client toward the auth server.	Uses `KIE_LA_CA_PATH` when set. Otherwise the agent does not reject the auth server certificate.
`service.js`	Wire Express routes and static files.	Loads env once, mounts the `/api/*` handlers, serves `public/`. Resolves `parentOrigin` from the embed request (query, `Origin`, or `Referer`).

API routes

Route	Role	Key points
`GET /api/config`	Safe data for the browser.	Exposes `authOrigin` (auth server base URL) and `labStack` — nothing secret. Your page calls this before `KieLaAuth.mount`.
`GET /api/auth/embed`	Hand out one iframe URL per request.	Called by `kie-la-auth.js` with `authUi` and your page origin. Returns `{ url }` built by `buildLoginEmbedUrl` (`embed=1` and `parent`).
`POST /api/session`	Turn iframe success into a logged-in visit.	Body: `{ exchange, parentOrigin }` from the iframe `postMessage`. Sets your session cookie; response includes `profile` for the signed-in UI.
`GET /api/me`	Restore session on reload.	Returns `{ profile }` when the cookie is valid; `401` otherwise. Call on page load — if OK, skip mounting the iframe and show the home view.

In your page

public/lib/kie-la-auth.js — copy this client (mount, resize, postMessage)
your-page.html — empty <div> mount points (see mount points)
your-page.css — layout around those divs (header, menu band, hero, …)

File	Role	Key points
`public/lib/kie-la-auth.js`	Browser client for the embed.	`KieLaAuth.mount({ minimalIframeRoot, authOrigin, authUi, onSuccess, … })` fetches embed URLs from your server, injects iframes, handles resize/focus `postMessage`, and POSTs `/api/session` after mobile approval. Returns `{ destroy, focus, showAuthUi }` — call `destroy()` once signed in.
`your-page.html`	Mount points and splash / home structure.	Empty `<div>` elements where the iframe goes (see the mount table). Typical pattern: public splash visible when logged out, private home hidden until `onSuccess`.
`your-page.css`	Layout around the mount divs.	You position the container (header flex, centered menu band, …); the iframe size comes from the auth server via `postMessage`. Use `overflow: visible` on mount divs so expanded pills are not clipped.

Academy live demos reuse the same kie-la-auth.js + /api/* pattern.

← Understand

How was the Academy? Tell us in your own words →