AuthKit-Lite quickstart

Prerequisites

The Maven wrapper is included, so system Maven is not required.

• Java 25 LTS
• Git
• A current browser
• MySQL 8 or later only when overriding the default H2 database

Clone and run

Do not create a .env file for this first run. AuthKit-Lite starts on port 8080 with an in-memory H2 database, applies its Flyway migrations, generates an ephemeral local JWT secret, and inserts demo users only when the users table is empty.

git clone https://github.com/buildbasekit/AuthKit-Lite.git
cd AuthKit-Lite
./mvnw spring-boot:run

git clone https://github.com/buildbasekit/AuthKit-Lite.git
Set-Location .\AuthKit-Lite
.\mvnw.cmd spring-boot:run

Runnable local defaults

Try the APIs in your browser

Open http://localhost:8080/api-test after startup. The same-origin browser console exposes the available authentication, user, administrator, operations, and optional passkey flows without adding a separate frontend runtime.

• Register a new user or sign in with a demo account.
• Keep the returned access and refresh tokens in the page's in-memory session.
• Call protected user and administrator APIs with their normal Bearer-token rules.
• Inspect request payloads, status codes, and response bodies from the response stream.

Run the automated verification

The integration suite uses isolated H2 and requires no Docker or external database. Import AuthKit-Lite-API.postman_collection.json when you want the repeatable guided workflow outside the browser.

• Expected: the default H2 configuration and migrations initialize successfully.
• Expected: authentication, refresh rotation, RBAC, operations, and security tests pass.
• Use a real browser authenticator to complete successful passkey ceremonies.

./mvnw clean verify

.\mvnw.cmd clean verify

✓ AuthKit-Lite is running locally, its APIs are available to try, and its integration suite has passed.

Configure for further development

Copy .env.example to .env only when changing the runnable defaults. Uncomment only the values your application needs; the root .env file is loaded automatically and ignored by Git.

# Example names only; provide values locally
DB_URL=<external-mysql-url>
DB_USERNAME=<database-user>
DB_PASSWORD=<database-password>
JWT_SECRET=<high-entropy-secret-at-least-32-characters>
AUTHKIT_DEMO_DATA_ENABLED=false
PASSKEY_ENABLED=true