Build with Lovable

Coming Soon

The Lovable integration is not ready yet. It stays locked until it passes a proven end-to-end acceptance.

AI Builder integration

Vibe-code the interface. Keep identity on a backend you own.

Lovable builds the browser experience. Authenik8 remains the only identity, session, authorization, data, and secrets authority.

One authentication authority

Do not enable Lovable Cloud authentication or Supabase authentication. Do not create a second users table, session system, token-refresh implementation, or backend. Never place OAuth secrets, database URLs, Redis URLs, private JWKs, or refresh secrets in the Lovable project.

How it works

Lovable owns the visual UI: pages, forms, components, loading and error states, and responsive behavior. It calls your API only through the Authenik8 client, which keeps access tokens in memory and lets the API rotate refresh tokens as HttpOnly cookies. Authenik8 owns registration, login, OAuth, token verification, refresh rotation, sessions, revocation, roles, admin operations, audit events, database access, and secrets. Lovable never reimplements any of that, because the client it is given already does it.

You need Node.js ^20.19 || ^22.12 || >=24, npm, Git, and a Lovable account.

Workflow

You can orchestrate the whole thing from ChatGPT with the Authenik8 Project Planner app, or work directly in Lovable. Both end in the same place: a frontend that only talks to the Authenik8 API.

1. Start the backend

npx create-authenik8-app@latest my-app --yes --preset fullstack \
  --frontend lovable --oauth google,github --git
cd my-app
npm run dev:lovable

npm run dev:lovable starts project-local PostgreSQL, migrations, seeding, package watchers, and the API. It does not start the reference frontend on port 5173.

Check the API when you want extra confidence:

curl http://localhost:3000/api/health/ready
npm test
npm run typecheck
npm run build
npm run openapi:check

Keep apps/web as the known-good React reference until the Lovable frontend passes the same authentication lifecycle.

2. Plan and validate in ChatGPT

1. In ChatGPT, select the Authenik8 Project Planner app (see the MCP page).
2. Describe your product as a plan, run validate_project_spec, then generate_lovable_integration.
3. The planner hands back the contract and the installable client sources. No generated project or export step is required to build the frontend.

Lovable connects to ChatGPT in the same chat: make the Authenik8 app and Lovable available to the chat, sign into the Lovable workspace where the frontend should be created, and follow the prompt sequence the planner returns. Apply LOVABLE_PROMPT.md one numbered step at a time, keeping the security rules unchanged.

3. Or go direct in Lovable

Skip ChatGPT if you prefer: copy the files from integrations/lovable/ in the generated repository into the context you give Lovable, install @authenik8/api-client from the exported archives, and apply the prompt sequence step by step:

openapi.json
FRONTEND_CONTRACT.md
SECURITY_RULES.md
LOVABLE_PROMPT.md
vendor/authenik8-contracts.tgz and vendor/authenik8-api-client.tgz

Run npm run export:lovable-client first to produce the archives. Commit before each prompt and review Lovable's diff before continuing; Lovable's GitHub sync is bidirectional.

4. Set public frontend configuration

In Lovable, set two public values. VITE_* values are compiled into browser code and are public; never put a secret there.

VITE_AUTHENIK8_API_URL=https://api.example.com
VITE_APP_URL=https://app.example.com

Create exactly one client instance and use it everywhere:

import {createAuthenik8Client} from '@authenik8/api-client';

export const authenik8 = createAuthenik8Client({
  baseUrl: import.meta.env.VITE_AUTHENIK8_API_URL,
});

Call authenik8.auth.restore() at startup and subscribe to authentication loss. Keep only the public user projection in UI state; never copy tokens into React state or browser storage.

5. Validate

From the Authenik8 backend repository:

npm run doctor:lovable -- /path/to/lovable-frontend

Or through the CLI:

npx create-authenik8-app@latest doctor frontend \
  --target lovable /path/to/lovable-frontend

Use --json in CI. The validator detects browser token storage, duplicate authentication calls, Supabase/Lovable auth, exposed secrets or private JWKs, unsafe CORS, trusted editable roles, direct admin access, and missing client configuration. A failure exits non-zero.

Deploy on same-site domains

Frontend  https://app.example.com     Lovable
API       https://api.example.com     Your API host

These are different origins but the same site, so the strict refresh and CSRF cookies work without weakening their attributes. A Lovable preview domain and api.example.com are cross-site; browser third-party-cookie policy can prevent the refresh lifecycle there. Use previews for visual work, then test login, refresh, logout, recovery, and OAuth on the custom domains.

1. Publish the frontend and connect app.example.com in Lovable.
2. Connect api.example.com to the API service.
3. Wait for valid HTTPS certificates on both domains.
4. Set the API's WEB_ORIGIN=https://app.example.com exactly. Credentialed CORS must never use *.
5. Set AUTHENIK8_ISSUER=https://api.example.com and COOKIE_SECURE=true.
6. Keep PostgreSQL, Redis, signing keys, refresh secrets, email credentials, and OAuth secrets on the backend host only.
7. Run database migrations as a controlled release step and require /api/health/ready to pass before routing traffic.
8. Repeat the generated acceptance checklist on the production domains.

Lovable supplies project-specific DNS records after publishing; copy the exact records it displays rather than example targets. See Lovable's official custom-domain guide.

OAuth callback URLs

Register these exact callbacks with Google and GitHub:

https://api.example.com/api/auth/oauth/google/callback
https://api.example.com/api/auth/oauth/github/callback

Keep the provider client secrets on the API. The callback exchanges a short-lived code once and removes it from the browser URL; the code is not an access token.

Security checklist

• Authenik8 is the only authentication and backend authority.
• Access tokens stay in memory only.
• Refresh and CSRF cookie behavior comes from the supplied client.
• The browser sends credentials only to the configured exact API origin.
• WEB_ORIGIN is one exact HTTPS frontend origin in production.
• Private JWK fields and all service credentials remain server-side.
• User roles come from the API, never editable browser state.
• Every project and administrator action is authorized by the API.
• Ordinary users receive 403 from admin endpoints even when opening routes manually.
• Account recovery, failed refresh, logout, provider unlinking, and session revocation are tested before release.

Common problems

Symptom	Check
Login works, then refresh loses the session	Test on same-site custom domains; cross-site preview cookies may be blocked
Browser reports a CORS failure	WEB_ORIGIN must exactly match the frontend scheme, host, and port; do not add a trailing path or wildcard
OAuth returns to the wrong place	Verify the provider callback, AUTHENIK8_ISSUER, and exact WEB_ORIGIN
Validator reports duplicate auth calls	Remove direct fetch/Axios auth code and use the one Authenik8 client instance
Provider unlink fails	The API prevents removing the final sign-in method; add another method first
Admin screen is hidden but endpoint is reachable	Hiding navigation is only UX; require backend admin middleware and verify an ordinary-user 403

The generated repository also includes integrations/lovable/TROUBLESHOOTING.md and integrations/lovable/acceptance-checklist.md for project-specific diagnosis and release evidence.