Signing keys and JWKS

Lumina Finance uses signing keys to verify that your session tokens came from your instance and haven't been altered. These keys are separate from APP_ENCRYPTION_KEY, which encrypts secrets stored in the database.

On a new installation, Lumina Finance generates these keys and saves them as access_private.pem and refresh_private.pem under /data/keys.

Using your own keys

To use your own keys, replace access_private.pem and refresh_private.pem in the app's /data/keys directory with two separate, valid, unencrypted RSA private keys in PEM format. Keep the existing filenames and make sure Lumina Finance can read both files. You don't need to change any mounts or environment variables when using these default paths.

Once you've replaced the files, restart the app to load the keys.

Using another directory or filename

If you'd like to use another directory or different filenames, set JWT_ACCESS_PRIVATE_KEY_PATH and JWT_REFRESH_PRIVATE_KEY_PATH in .env to the full paths inside the app container.

Example

To use access.pem and refresh.pem in /data/signing-keys, set:

JWT_ACCESS_PRIVATE_KEY_PATH=/data/signing-keys/access.pem
JWT_REFRESH_PRIVATE_KEY_PATH=/data/signing-keys/refresh.pem

Verifying JWT signatures

Lumina Finance exposes its public keys as a JSON Web Key Set (JWKS) at /api/auth/.well-known/jwks.json. Gateways and reverse proxies that support JWT verification can use these keys to verify JWT signatures before forwarding requests to the application. For details on how to configure this, please refer to the documentation of the gateway or reverse proxy that you are using.