Platform bootstrap

Authfy initializes its system administrator and support application after the API becomes ready. There is no public bootstrap or manual seeder endpoint.

Required configuration

Configure these values on the Auth API:

BOOTSTRAP_ADMIN_EMAIL=admin@example.com
BOOTSTRAP_ADMIN_NAME=System Admin
BOOTSTRAP_ADMIN_PASSWORD=replace-with-a-strong-password

• BOOTSTRAP_ADMIN_EMAIL identifies the administrator and receives the support console access key email after every API restart.
• BOOTSTRAP_ADMIN_NAME is used when the configured account is created or promoted to SYSTEM_ADMIN.
• BOOTSTRAP_ADMIN_PASSWORD is required only when Authfy must create a new administrator. Authfy hashes it before storage.

The old BOOTSTRAP_SECRET setting is not used.

What happens at startup

When Spring publishes ApplicationReadyEvent, Authfy:

1. Uses the account matching BOOTSTRAP_ADMIN_EMAIL when it is already a SYSTEM_ADMIN; otherwise it uses the oldest existing system administrator.
2. If no system administrator exists, it promotes the configured account or creates it from the bootstrap settings.
3. Creates or synchronizes Default Company.
4. Creates or synchronizes the support app application with App ID support-app.
5. Ensures the support application has a usable access key for the support console. A default key is created only if no usable key exists; its Allowed URLs default to http://localhost:3004 and are configurable via app.bootstrap.support.allowed-urls.
6. Makes the system administrator an active owner of Default Company and keeps the company subscribed to the support application.
7. Queues an email to BOOTSTRAP_ADMIN_EMAIL containing the current access key's public key and fingerprint.

Synchronization and key delivery run on every API restart. Existing resources are updated in place rather than duplicated. Key material is generated exactly once when a key is created and is never silently regenerated — if the configured KEY_ENCRYPTION_SECRET no longer decrypts the stored private keys, startup fails loudly instead of replacing them.

Configure the support console

Copy the access key public key from the startup email into the support application's configuration:

AUTH_API_URL=http://localhost:8081
AUTH_VIEW_URL=http://localhost:3001
APP_URL=http://localhost:3004
APP_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqh...\n-----END PUBLIC KEY-----"

APP_PUBLIC_KEY is the sole client credential — there is no AUTH_APP_ID. Preserve the PEM header and footer; when the value is stored on one line, represent line breaks as \n.

Restart the support application after changing APP_PUBLIC_KEY, because Next.js loads environment variables when its process starts.

Email delivery requirements

The key message uses Authfy's configured platform notification pipeline. Ensure the API has valid SMTP or SES settings and can reach its notification queue. If the message cannot be queued, startup reports the email delivery failure in the API logs.

The public key is safe to distribute to the support application. The private key remains encrypted inside Authfy and is never included in the email.

Key rotation

Access key material is never regenerated in place. To rotate the support console's key, create a replacement access key for the support application on the Access keys page, update APP_PUBLIC_KEY, restart the support application, and then revoke the old key. If you are unsure which key is current, restart the Auth API — the startup email always carries the current key's public key and fingerprint.