Authentication & Device Flow

Lovelace uses the device authorization flow (OAuth 2.0 Device Code Grant) to securely authenticate your Neovim extension without requiring you to enter passwords in the editor.

Check Authentication Status

Run the authentication command to check if you're already authenticated:

:LovelaceAuth

Already Authenticated

If you're already authenticated, you'll see your account information:

# Authentication Status

**User**: user@example.com
**User ID**: usr_abc123def456
**Device**: Paired
**Session**: Active

Press 'q' to close

Keybinding: Press q to close the window

Device Authorization Flow

If you're not authenticated, the device code UI appears automatically:

# Device Authorization Required

To authorize this device, visit:
https://uselovelace.com/device

And enter code: ABCD-EFGH

Keybindings:
  c - Copy code to clipboard
  o - Open browser to verification URL
  q - Cancel authentication

Waiting for authorization...

Step-by-Step Authorization

1. Copy the code:

   vim

   " Press 'c' in the device code window
   " Code is copied to clipboard
   

2. Open browser:

   vim

   " Press 'o' to open verification URL
   " Browser opens to https://uselovelace.com/device
   

3. Authorize in browser:

   • Paste the code (Cmd+V or Ctrl+V)
   • Click "Authorize"
   • Confirm the device authorization

4. Wait for completion:

   • The plugin polls for authorization every 5 seconds
   • Window closes automatically when successful
   • Notification: "Authentication successful! Welcome to Lovelace."

Keybindings in Device Flow

Device Code Expiration

Device codes expire after 10 minutes. If you see this error:

Device code expired. Please try again.

Solution: Restart the authentication flow:

:LovelaceAuth

Troubleshooting Authentication

Authorization Not Completing

Symptom: Device flow window stays open, "Waiting for authorization..." doesn't change

Solutions:

1. Check browser authorization:

   • Verify you clicked "Authorize" in the browser
   • Check for error messages in the browser
   • Ensure the code matches exactly

2. Check internet connection:

   • Device flow requires internet access
   • Firewall may be blocking OAuth endpoints

3. Try manual authorization:

   bash

   # Visit URL manually
   open https://uselovelace.com/device
   
   # Enter code manually (from device code window)
   

4. Enable debug logging:

   lua

   require("lovelace").setup({
     log_level = "debug"
   })
   

   Then check :messages for authorization polling logs

"Authentication failed" Error

Symptom: Error notification after device flow completes

Solutions:

1. Verify user account status:

   • Ensure your Lovelace account is active
   • Check email for account verification

2. Check daemon logs:

   bash

   localhost-ctl logs | grep auth
   

3. Restart authentication:

   vim

   :LovelaceAuth
   

Browser Doesn't Open

Symptom: Pressing o doesn't open browser

Solutions:

1. Manually visit URL:

   • URL is shown in the device code window
   • Copy and paste into browser

2. Check default browser configuration:

   bash

   # macOS
   open https://uselovelace.com/device
   
   # Linux
   xdg-open https://uselovelace.com/device
   

Authentication State Management

Session Persistence

Once authenticated:

• Session persists across Neovim restarts
• No need to re-authenticate every time
• Token automatically refreshed in background

Re-authentication

You'll need to re-authenticate if:

• Token expires (typically after 90 days)
• You revoke device access in account settings
• Daemon is reset or reinstalled

Check Current Auth Status

Use the health check command:

:LovelaceHealth

The authentication section shows your current status.

Security Considerations

Device Authorization Benefits

• No passwords in editor: Credentials never touch Neovim
• Revocable access: Devices can be revoked in account settings
• Limited scope: Only grants access needed for task submission
• Secure token storage: Tokens stored by daemon, not Neovim

Token Security

Where tokens are stored:

• macOS: Keychain
• Linux: libsecret or encrypted file
• Windows: Windows Credential Manager

Token rotation: Tokens are automatically refreshed before expiration

Workflow Integration

First-Time Setup

1. Install extension: See Installation Guide
2. Start daemon: localhost-ctl start
3. Run health check: :LovelaceHealth
4. Authenticate: :LovelaceAuth
5. Submit first task: Ready to go!

Regular Usage

Authentication is automatic after initial setup. You only interact with :LovelaceAuth if:

• Checking current authentication status
• Troubleshooting auth issues
• Re-authenticating after token expiration

Next Steps

• Task Submission - Submit your first task
• Health Check - Verify daemon connection
• Command Reference - Full :LovelaceAuth documentation
• Troubleshooting - Common authentication issues

Related Documentation

• Installation Guide - Complete setup instructions
• Quick Start Tutorial - First task walkthrough
• :LovelaceAuth Command - Full command reference