Authentication

dxflow offers two ways to sign in, and both end in a JWT session with a configurable lifetime.

• Private key — challenge-response with an RSA key pair, so you prove you own the key without ever sending it. The browser remembers yours, making repeat sign-ins a single click. Multiple keys are supported, each with its own permissions.
• Pairing code — a short code printed by the engine host and approved there. Suited to a server you reach over SSH, where copying the key to your laptop would be the only alternative.

Signing in with a private key

Signing in with a pairing code

Use this when the engine runs somewhere you have shell access, such as an EC2 instance or any cloud VM. The private key stays on the server.

dxflow engine pair

● Pairing
  Permissions  SHELL, ARTIFACT, RUNTIME, WORKFLOW, AGENT
  Code         K7QM3XPD
  Waiting 30s for a console to use the code

● Pairing request
  Address      203.0.113.9
  Agent        Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
  Approve? [y/N] y
Pairing approved: the console is signed in

Scope the session with flags on the command:

dxflow engine pair --permissions SHELL,RUNTIME   # limit what the session can do
dxflow engine pair --lifetime 24h                # 1 minute to 24 hours, default 1 hour

A code lasts 30 seconds, and you get a further 30 seconds to answer once a console claims it. It works once — approving, rejecting, and letting it expire all consume it — so every session starts with a fresh dxflow engine pair. The browser keeps nothing afterwards, which makes pairing a good fit for a shared or borrowed machine.

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>

Register a key with a narrower scope by passing --permissions; a key registered without them receives SHELL,ARTIFACT,RUNTIME,WORKFLOW,AGENT. See the permission model.

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.

Pairing uses one endpoint from a client's side: POST /api/auth/pair/request/ with { "code": "K7QM3XPD" }. It streams a confirmation that the code was accepted, holds the connection while the operator decides, and answers with the same token, permissions, and expires_at on approval. A rejected, unknown, expired, or already-claimed code answers 401.

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