Two configuration layers
-
deployment TOML - The identity deployment describes its node, private state directory, network, issuer, database, permission engine, clients and credential sources.
-
directory JSON - The running directory has a separately rendered JSON configuration with its listener, event and grant logs, OIDC client, permission model and optional services.
-
event_key_file - Private signing material for directory events. The configuration names a path.
-
issuer / client_id / client_secret_file - The directory’s OIDC registration. Keep the secret in its file.
-
grant_log_dir / grant_model_file - The grant history and the permission model it is judged against.
-
profile - A service installation has no standing operator-token authority. Development profile is a separate explicit mode.
-
sessions_file - Persistent signed-in sessions when configured; without it, sessions are in memory.
-
spicedb / secrets - Optional service settings. Missing dependent features refuse by name.
Validate at the boundary
The typed loaders reject unknown members and invalid addresses with the field’s name. Preparation validates the deployment before writing or sending its artifacts. Configuration registers the intended application clients; it is a change, not a readiness probe.
Validate the deployment configuration and materialise its private artifacts: generated or provided credentials and the compose environment, each owner-only in the state directory. Existing credentials are reused, never rotated
lys identity prepare [OPTIONS] --config <CONFIG>-
--config <CONFIG> - The deployment configuration (see deploy/identity/config.example.toml).
Register the platform's and the installed app's clients in Rauthy and apply their themes. Idempotent: a second run changes nothing and reports the same operation identifiers. Rauthy's built-in client is never touched
lys identity configure [OPTIONS] --config <CONFIG>-
--config <CONFIG> - The deployment configuration.
Preparation and configuration write private deployment state. Read the named field in any refusal before repeating either operation.
Features and their dependencies
Directory, grants, runtime, network and secrets have separate stored state and service dependencies. A missing configured capability is answered by its named unavailable refusal. Public directory health cannot prove every dependent route works.
Keep the identity intact
Preserve signing material, origins, grant history and private state through maintenance. Replacing a private file to make a service start can change the identity that historical records depend on. Use the installation lifecycle and its receipts for a deliberate change.