Skip to content
IAM

Quickstart

This is the fastest path from empty project to a running app with authentication, permissions, and an admin user — using local-dev defaults. The whole exercise is three steps.

1. Add the starter

Section titled “1. Add the starter”
build.gradle.kts
dependencies {
    implementation(platform("dev.mpofusindie:iam-bom:2.0.0"))  // aligns every iam-* version
    implementation("dev.mpofusindie:iam-spring-boot-starter")
    runtimeOnly("org.postgresql:postgresql")
    runtimeOnly("org.flywaydb:flyway-core")
    runtimeOnly("org.flywaydb:flyway-database-postgresql")
}

The BOM pins every iam-* module to one version, so you declare modules version-free. The starter transitively brings Spring Web, Data JPA, Security, Validation, and AOP — you don’t declare them yourself.

2. A few lines of configuration

Section titled “2. A few lines of configuration”
application.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/myapp
    username: myapp
    password: secret


iam:
  dev-mode: true        # LOCAL DEV ONLY: ephemeral JWT/admin secrets are generated at boot

There is no profile to include and no packaged config file: every IAM default lives in code (@ConfigurationProperties), so the starter never competes with your own application.yml. (Configs from earlier 2.0.0 builds that still say spring.profiles.include: iam keep booting — the profile is simply a no-op now.)

3. Start it

Section titled “3. Start it”
Terminal window
./gradlew bootRun

On startup IAM will:

  1. Run its schema migrations through IAM’s own dedicated Flyway instance (db/iam/migration/postgresql by default, history table iam_flyway_history) — your spring.flyway.* setup is untouched, and all IAM tables are prefixed iam_ and use IF NOT EXISTS, so they coexist with your schema.
  2. Seed a default tenant, an admin user (admin@localhost, generated password logged in dev-mode), the SUPER_ADMIN role, and 17 system actions (CRUD, export, approve, …).
  3. Register your resources from any @RequiresPermission annotations it finds (how that works).
  4. Expose the full REST API under /api/iam/v1/ — login, refresh, /me/permissions, and the management endpoints — plus OpenAPI docs.

4. Log in

Section titled “4. Log in”
Terminal window
curl -X POST localhost:8080/api/iam/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "admin@localhost", "password": "<from the startup log>"}'

The response contains a JWT access token. Use it to fetch the resolved permission object your frontend will consume:

Terminal window
curl localhost:8080/api/iam/v1/me/permissions -H "Authorization: Bearer $TOKEN"

Where to next

Section titled “Where to next”