Authentication
You sign in to dxflow with an RSA key pair. It's challenge-response: you prove you own your private key without ever sending it. Keys are created automatically on first engine startup, so no manual setup is needed. Sessions are JWT tokens with a configurable lifetime, and multiple keys are supported.
Getting started
Locate your private key
Generate a key pair with dxflow key generate [NAME]. It writes <name>.pem (private) and <name>.pub (public) to your current directory (default name rsa). Keep the .pem file safe — it is your private key.
dxflow key list shows the public keys authorized on the engine (stored in ~/.dxflow/authorized_keys), not your local private key files.
Open the login page
- Local installation:
http://localhost(or your configured port) - Remote server:
http://<your-server-ip>:<port>
Sign in
The web interface walks you through signing in with your private key.
Key management
# List authorized keys (by IDENTITY)
dxflow key list
# Generate a new key pair (optional NAME, default "rsa")
dxflow key generate [NAME]
# Register an additional public key
dxflow key register <public-key-file>
# Remove a key
dxflow key unregister <key-identity>
Best practices:
- Store private keys with restrictive permissions and never share them.
- Use a separate key per environment (dev/prod) and rotate keys in high-security setups.
- Back up
.pemfiles safely and note each key's identity and purpose. - Watch authentication logs and alert on failed attempts.
Session management
Sessions use JWT tokens with a lifetime of 1 minute to 24 hours (default 1 hour). They:
- Persist across browser tabs and survive page refresh and navigation
- Renew automatically during active use and stay in sync across tabs
- End on logout, and expired tokens are cleaned up automatically
Calling the API directly
To authenticate from your own code, use these three endpoints. You sign the challenge with your private key, so the key is never sent.
| Step | Endpoint | What it returns |
|---|---|---|
| Request a challenge | GET /api/auth/challenge/ | identity, nonce, lifetime |
| Sign and verify | POST /api/auth/verify/ | A JWT token, permissions, and expires_at |
| Check a session | GET /api/auth/inspect/ | Confirms whether the JWT (sent in the request headers) is still valid |
Challenge response:
{
"identity": "your-key-identity",
"nonce": "random-challenge-string",
"lifetime": "1m0s"
}
Verify response. Send an optional lifetime (e.g. "1h") to set the token duration. Range is 1 minute to 24 hours; out-of-range or omitted values use the 1 hour default.
{
"token": "jwt-authentication-token",
"permissions": ["SHELL", "ARTIFACT", "WORKFLOW"],
"expires_at": 1640995200
}
Troubleshooting
| Symptom | Checks |
|---|---|
| Cannot locate private key | Run dxflow key list; verify the local .pem exists with correct permissions; ensure ~/.dxflow/ exists |
| Authentication fails repeatedly | Verify the system clock is accurate (affects token timing); check the key isn't corrupted/modified; try dxflow key generate |
| Browser shows "Unauthorized" | Clear cache/cookies; disable interfering extensions; try incognito/private mode |
| Session expires too quickly | Check engine session-timeout config; verify time sync; request a longer lifetime |
| Session not maintained across tabs | Enable cookies; ensure browser storage is available and not blocked by security policies |
| Frequent logouts | Check network stability; verify the engine runs continuously; review logs for timeout patterns |
| Lost or corrupted keys | Run dxflow key generate; update automation scripts with the new key identity |
| Permission denied | Verify the key has permissions for the operation; check user role assignments; confirm the key is registered (dxflow key list) |
| Multiple key conflicts | List keys to find duplicates; remove unused ones with dxflow key unregister <identity>; keep names/identities unique |
Security considerations
- Network: use HTTPS in production, restrict access via firewall/VPN, and monitor authentication traffic for anomalies.
- Operational: audit authentication logs and user access regularly, and keep an incident-response procedure for compromised keys.