OAuth 2.1 Authentication¶

Connect to EcoSemantic using OAuth 2.1 for secure, user-authorized access with automatic token management.

Overview¶

OAuth 2.1 provides the most secure way to connect AI chat applications to EcoSemantic:

🔐 Secure Authorization - Users explicitly authorize access
🔄 Automatic Token Refresh - No manual token management
🎯 Granular Permissions - Request only needed scopes
🚫 Easy Revocation - Users can revoke access anytime

How It Works¶

sequenceDiagram
    participant User
    participant Claude
    participant EcoSemantic

    User->>Claude: Start conversation
    Claude->>EcoSemantic: Request authorization
    EcoSemantic->>User: Show consent screen
    User->>EcoSemantic: Grant permission
    EcoSemantic->>Claude: Return access token
    Claude->>EcoSemantic: Make API calls

Setup with Claude Desktop¶

Step 1: Install Claude Desktop¶

Download and install Claude Desktop (version 0.7.0+) from the official website.

Step 2: Configure MCP with OAuth¶

Open Claude Desktop settings
Navigate to MCP Servers
Add EcoSemantic with OAuth configuration:

{
  "mcpServers": {
    "EcoSemantic": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.ecosemantic.com/mcp"
      ]
    }
  }
}

:::note OAuth Authentication OAuth authentication happens automatically when you first use an EcoSemantic tool. Claude will prompt you to authorize access through your browser. :::

Step 3: First Connection¶

Start a conversation in Claude
When you first use an EcoSemantic tool, you'll see an authorization prompt
Click "Authorize" to open the consent screen
Review the requested permissions
Click "Allow Access"
You'll be redirected back to Claude

Step 4: Verify Connection¶

Test with this prompt:

Search for solar panel activities in Ecoinvent 3.9.1

Claude should use the search_activities tool with your authorized credentials.

Permissions and Scopes¶

EcoSemantic requests the following scopes:

Scope	Description	Required
`lca:read`	Read LCA data and calculations	Yes
`lca:calculate`	Perform LCA calculations	Yes
`projects:read`	View custom projects	Optional
`projects:write`	Create/modify custom projects	Optional

Managing Access¶

View Connected Apps¶

Log in to your EcoSemantic dashboard
Go to Settings → Connected Apps
View all authorized applications

Revoke Access¶

To revoke OAuth access:

Go to Settings → Connected Apps
Find the connected application
Click "Revoke Access"
The app will immediately lose access

Token Lifecycle¶

Access Tokens¶

Lifetime: 1 hour
Refresh: Automatic
Storage: Secure, client-managed

Refresh Tokens¶

Lifetime: 90 days
Usage: Auto-renewed on use
Revocation: Manual or automatic after 90 days

Troubleshooting¶

Authorization Failed¶

Problem: OAuth authorization doesn't complete

Solutions: - Ensure you're logged into EcoSemantic - Check browser popup blockers - Try a different browser - Clear browser cache and cookies

Token Expired¶

Problem: "Token expired" error

Solutions: - This should auto-refresh; if not, reconnect - Check your internet connection - Restart Claude Desktop

Permission Denied¶

Problem: "Insufficient permissions" error

Solutions: - Revoke and re-authorize with correct scopes - Verify your subscription tier supports the feature - Contact support if issue persists

Security Best Practices¶

For Users¶

✅ Only authorize trusted applications
✅ Regularly review connected apps
✅ Revoke unused authorizations
✅ Use strong EcoSemantic account password

For Developers¶

✅ Request minimum required scopes
✅ Handle token refresh properly
✅ Store tokens securely
✅ Implement proper error handling

OAuth vs API Token¶

Aspect	OAuth 2.1	API Token
User Authorization	Required	Not required
Token Lifetime	Short (auto-refresh)	Long (manual)
Security	Highest	High
Setup	Medium complexity	Simple
Best For	Production apps	Development