Documentation Index
Fetch the complete documentation index at: https://docs.keyboard.dev/llms.txt
Use this file to discover all available pages before exploring further.
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