Authentication

How authentication works across the BridgeMind ecosystem — API keys, OAuth, JWT tokens, and desktop app authentication flows.

BridgeMind uses different authentication methods depending on where you're connecting from. This guide covers all of them.

Overview

Method	Used By	How It Works
API Key	BridgeMCP, direct API calls	Static key passed in headers
OAuth 2.0 + JWT	BridgeSpace, BridgeVoice, BridgeCode	Browser-based login, token exchange
Google OAuth	Web dashboard	Google sign-in via the BridgeMind website

API Keys

API keys are the simplest way to authenticate with BridgeMind. They're used primarily by MCP servers and direct API integrations.

Generating a Key

Sign in to the BridgeMind dashboard at bridgemind.ai
Navigate to Settings → API Keys
Click Generate New Key
Copy the key immediately — it won't be shown again

Using Your Key

Pass the API key in the Authorization header:

Authorization: Bearer bm_live_abc123...

Or as a query parameter (fallback for clients that can't set headers):

?apiKey=bm_live_abc123...

Key Scoping

Each API key is scoped to your account. An agent using your key can:

List and create projects you own
Create, read, and update tasks in your projects
Manage agents in your projects

Keys cannot access other builders' projects or perform account-level operations (billing, profile changes).

Key Security

Store keys in environment variables, never in source code
Rotate keys periodically from the dashboard
Delete keys you're no longer using
Each key can be independently revoked

OAuth 2.0 (Desktop Apps)

BridgeSpace, BridgeVoice, and BridgeCode use OAuth 2.0 with PKCE for secure authentication from desktop applications.

How It Works

You click "Sign In" in the desktop app
The app opens your system browser to the BridgeMind login page
You authenticate with Google OAuth or email/password
The browser redirects to the app via a deep link callback (e.g., bridgespace://auth/callback)
The app exchanges the authorization code for JWT tokens
Tokens are encrypted and stored locally using AES-GCM

PKCE Security

All desktop OAuth flows use Proof Key for Code Exchange (PKCE):

The app generates a random code_verifier
A code_challenge is derived using SHA-256
The challenge is sent with the authorization request
The verifier is sent with the token exchange
The server validates that the verifier matches the challenge

This prevents authorization code interception attacks.

Token Storage

Desktop apps encrypt tokens before storing them on disk:

Algorithm: AES-256-GCM
Key derivation: Device fingerprint + app-specific salt
Storage location: App data directory (platform-specific)
Scope: Tokens are bound to the device they were issued on

Token Refresh

JWT access tokens expire after a short period. Desktop apps handle refresh automatically:

Tokens are refreshed 2 minutes before expiry
If a refresh is missed (e.g., laptop was asleep), it's retried on the next window focus
If the refresh token itself expires, you'll be prompted to sign in again

JWT Tokens

The BridgeMind API issues JWT tokens for authenticated sessions.

Access Token

Short-lived (configurable, typically 15–60 minutes)
Passed in the Authorization: Bearer header
Contains: user ID, roles, subscription status
Used for all API requests

Refresh Token

Long-lived (configurable, typically 7–30 days)
Used only to obtain new access tokens
Encrypted at rest on desktop apps
Rotated on each use (one-time use)

Google OAuth

The BridgeMind web dashboard uses Google OAuth for sign-in:

Click "Sign in with Google" on the login page
Authenticate with your Google account
BridgeMind receives your profile information (name, email, avatar)
A BridgeMind account is created or linked automatically
You're redirected to the dashboard with an active session

Google OAuth is the primary authentication method for new builders.

Authentication by Product

BridgeMCP

Uses API keys. Configure your key in the MCP server setup:

{
  "env": {
    "BRIDGEMIND_API_KEY": "your_api_key_here"
  }
}

See the BridgeMCP installation guide for full setup.

BridgeCode

Uses OAuth 2.0. Authenticate from the terminal:

bridgecode auth login

This opens your browser for authentication and stores tokens locally.

Verify the key is correct and hasn't been revoked
Check the key is being sent in the Authorization: Bearer header
Ensure there are no trailing spaces or newlines in the key value

Make sure your default browser is set correctly
Check that the deep link protocol is registered (reinstall the app if needed)
Try signing out and back in from the app's settings

Token refresh failures

Sign out and sign back in to get fresh tokens
Check your internet connection — refresh requires an API call
If the issue persists, regenerate your API key or re-authenticate