Authentication

Step 1: Request Challenge

• Endpoint: GET /api/auth/challenge/
• Purpose: Generate unique authentication challenge
• Returns: Challenge data with identity, nonce, and lifetime

{
  "identity": "your-key-identity",
  "nonce": "random-challenge-string",
  "lifetime": 300
}

Step 2: Sign and Verify

• Endpoint: POST /api/auth/verify/
• Purpose: Verify signature against challenge
• Process: Your private key signs the challenge data
• Returns: JWT authentication token on success

{
  "token": "jwt-authentication-token",
  "expires": 1640995200
}

Step 3: Session Management

• Endpoint: GET /api/auth/inspect/
• Purpose: Validate current authentication state
• Headers: Requires valid JWT token
• Returns: Current session information and permissions

{
  "authenticated": true,
  "identity": "your-key-identity",
  "permissions": ["SHELL", "OBJECT", "WORKFLOW"],
  "expires": 1640995200
}

Safeguard Your Keys

• Store private keys securely with appropriate file permissions
• Never share private keys with others
• Use different keys for different environments (dev/prod)
• Regular key rotation for high-security environments

Key Backup Strategy

• Backup key files to secure location
• Document key identities and their purposes
• Test key restore procedures
• Maintain key recovery procedures

Security Monitoring

• Monitor authentication logs for suspicious activity
• Track key usage patterns
• Set up alerts for failed authentication attempts
• Regular security audits of key access

Cannot locate private key:

• Check if keys exist: dxflow engine key list
• Verify key file permissions are correct
• Ensure .dxflow/keys/ directory exists

Authentication fails repeatedly:

• Verify system clock is accurate (affects token timing)
• Check if key has been corrupted or modified
• Try generating a new key: dxflow engine key generate

Browser shows "Unauthorized" errors:

• Clear browser cache and cookies
• Disable browser extensions that might interfere
• Try authentication in incognito/private browsing mode

Session expires too quickly:

• Check engine configuration for session timeout settings
• Verify system time synchronization
• Consider increasing session duration for your use case

Cannot maintain session across tabs:

• Ensure cookies are enabled in browser
• Check if browser storage is available
• Verify no browser security policies blocking session storage

Frequent logouts:

• Check network stability and connection quality
• Verify engine is running continuously
• Review authentication logs for timeout patterns

Lost or corrupted keys:

• Generate new key pair: dxflow engine key generate
• Update any automation scripts with new key identity
• Document new key information securely

Permission denied errors:

• Verify key has proper permissions for required operations
• Check user role assignments in engine configuration
• Ensure key is properly registered: dxflow engine key list

Multiple key conflicts:

• List all keys to identify duplicates or conflicts
• Remove unused keys: dxflow engine key unregister <identity>
• Ensure unique key names and identities