Getting started
OAuth connections allow you to securely connect to external services like Google, GitHub, and Microsoft without sharing your passwords. The system uses industry-standard security to keep your data safe.Accessing OAuth settings
- Open Settings: In the Desktop App, click the settings icon or navigate to the Settings panel
- Navigate to OAuth: You’ll see four tabs at the top:
- WebSocket
- Encryption
- OAuth Providers ← Click here for direct connections
- Server Providers ← Click here for server-managed connections
OAuth Providers tab
This is where you manage direct connections to services using your own app credentials.What you’ll see
Provider Cards: Each service appears as a card showing:- Provider icon and name (e.g., Google, GitHub)
- Connection status: “Not Connected”, “Connected”, or “Expired”
- Scopes: What permissions the app has access to
- Action buttons: Connect, Refresh, Token, Disconnect
Built-in providers
The system comes with pre-configured providers:Google 🔍
- Status shown: Connected/Expired/Not Connected
- Scopes: openid, email, profile, drive.readonly, gmail.readonly, spreadsheets, presentations, drive.file
- What you can do: Access Google Drive, Gmail, Sheets, Slides
GitHub 🐙
- Scopes: user:email, repo
- What you can do: Access repositories and user profile data
Connecting to a provider
- Find the provider card you want to connect to
- Check requirements: If you see ⚠️ “This provider needs a Client ID to be configured”, you’ll need to add credentials first
- Click “Connect” button
- Browser opens: You’ll be redirected to the provider’s login page
- Sign in: Enter your credentials on the provider’s website
- Grant permissions: Review and approve the requested access
- Return to app: You’ll be redirected back automatically
- Success: The card now shows “Connected” with a green badge
Managing connected providers
Once connected, you’ll see additional options:📋 Copy token
- Click to copy your access token to clipboard
- Use this token in other applications or scripts
- Security note: Tokens are sensitive - don’t share them
🔄 Refresh (if expired)
- Appears when your connection has expired
- Click to get a new access token
- Usually happens automatically
❌ Disconnect
- Removes the connection and deletes stored tokens
- You’ll need to reconnect to use the service again
Adding custom providers
Need to connect to a service that’s not built-in? You can add your own!Step 1: Click ”➕ Add Provider”
Located at the top of the OAuth Providers tab.Step 2: Fill out the form
You’ll see a form with these fields:Required fields ⚠️
- Provider ID: Unique name (like “slack” or “discord”)
- Cannot be changed after creation
- Use lowercase letters and hyphens
- Display Name: What users see (like “Slack” or “Discord”)
- Client ID: From your OAuth app settings
- Authorization URL: Where users go to log in
- Token URL: Where the app exchanges codes for tokens
Optional fields
- Icon: Emoji to represent the service (🔗 is default)
- Client Secret: Some services require this
- User Info URL: To fetch user profile data
- Scopes: What permissions to request
- Redirect URI: Usually http://localhost:8082/callback
Quick templates
The form includes buttons for popular services:- Google 🔍: Pre-fills Google’s settings
- GitHub 🐙: Pre-fills GitHub’s settings
- Microsoft 🪟: Pre-fills Microsoft’s settings
- Discord 💬: Pre-fills Discord’s settings
Step 3: Save and connect
- Click ”✅ Add Provider”
- Your new provider appears in the list
- Click “Connect” to set up the connection
Server Providers tab
Server Providers let you connect through centralized OAuth servers managed by your organization.What you’ll see
Server List: Shows configured OAuth servers with:- Server name and URL (e.g., “My OAuth Server” at https://api.keyboard.dev)
- Available providers from that server
- Connection status for each provider
- Remove button to delete servers
Adding a server
- Click “Add Server” button (top right)
- Fill in the form:
- Server Name: Friendly name for your server
- Server URL: The server’s base URL (e.g., http://localhost:4000)
- Click “Add Server”
- Server appears in the list and fetches available providers
Using server providers
Once a server is added:Available providers section
Shows providers configured on that server:- 🟢 Green dot: Provider is configured and ready
- 🔴 Red dot: Provider needs server-side setup
- Provider name: Like “Google” or “X”
- Connection status: Connected/Expired/Not Connected
Connecting through server
- Find a provider with green status dot
- Click ”🔗 Connect”
- OAuth flow begins (same as direct providers)
- Authentication managed by the server
Managing server connections
Connected providers show:- 📋 Token: Copy access token
- 🔄 Refresh: Get new token (if expired)
- ❌ Disconnect: Remove connection
Understanding connection status
Status indicators
🟢 Connected
- You’re successfully authenticated
- Tokens are valid and not expired
- Ready to use the service
🔴 Expired
- Your access token has expired
- Click ”🔄 Refresh” to get a new one
- May happen automatically in background
⚪ Not connected
- No active connection to this service
- Click ”🔗 Connect” to set up authentication
User information
When connected, you’ll see:- 👤 User name or email
- 📅 Connection date: When you first connected
- 🔄 Last updated: When tokens were last refreshed
Managing your vonnections
Top-level actions
🔄 Refresh
Updates the list of all providers and their status.🗑️ Clear all
⚠️ Careful! This removes ALL OAuth connections at once.- Appears when you have active connections
- Requires confirmation before proceeding
- Cannot be undone
Troubleshooting
Common issues
”No Client ID” warning
What it means: The provider needs OAuth app credentials to work. How to fix:- Edit the provider (✏️ button)
- Add your Client ID and Client Secret
- Save changes and try connecting again
”Authentication Error”
What might be wrong:- Incorrect Client ID or Client Secret
- Wrong redirect URI in your OAuth app settings
- Service is temporarily unavailable
- Double-check your OAuth app settings
- Ensure redirect URI is http://localhost:8082/callback
- Try refreshing the page and connecting again
”Token Expired”
Normal behavior: Tokens expire for security. What to do:- Click ”🔄 Refresh” button
- If refresh fails, click ”❌ Disconnect” then ”🔗 Connect” again
Security notes
What’s protected
- 🔐 All tokens encrypted: Stored securely on your device
- 🛡️ PKCE security: Protection against code interception
- 🔒 File permissions: Storage files are locked to your user account
- ⏰ Token expiration: Automatic cleanup of old tokens
Best practices
- 🔄 Regular refresh: Let the system refresh tokens automatically
- ❌ Disconnect unused: Remove providers you no longer need
- 👀 Review scopes: Only grant necessary permissions
- 🔐 Keep credentials secure: Don’t share Client IDs or secrets
Quick reference
OAuth Providers tab
- Connect: Set up new connection
- Token: Copy access token
- Refresh: Get new token
- Disconnect: Remove connection
- Add Provider: Create custom provider
Server Providers tab
- Add Server: Connect to OAuth server
- Remove: Delete server configuration
- Refresh: Update provider list
- Connect: Authenticate through server
Status colors
- 🟢 Green: Connected and active
- 🔴 Red: Expired or error
- ⚪ Gray: Not connected