Skip to content

API Token Authentication

Connect to EcoSemantic using API tokens for direct, simple access. Perfect for development, testing, and automation.

Overview

API tokens provide straightforward authentication:

  • ⚡ Quick Setup - Get started in minutes
  • 🔧 Development Friendly - Perfect for testing
  • 🤖 Automation Ready - Great for scripts
  • 🔑 Long-Lived - Tokens don't expire automatically

Getting Your API Token

Step 1: Sign Up

  1. Go to ecosemantic.com
  2. Click "Sign Up"
  3. Complete registration
  4. Verify your email

Step 2: Generate Token

  1. Log in to your dashboard
  2. Navigate to Settings → API Tokens
  3. Click "Generate New Token"
  4. Give your token a descriptive name (e.g., "Claude Desktop")
  5. Click "Create"
  6. Copy the token immediately - you won't see it again!

:::warning Keep Your Token Secure API tokens provide full access to your account. Never commit them to version control or share them publicly. :::

Using with Claude Desktop

Configuration File Location

Choose based on your operating system:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Configuration Example

{
  "mcpServers": {
    "EcoSemantic": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.ecosemantic.com/mcp",
        "--header",
        "Authorization:Bearer your-api-token-here"
      ]
    }
  }
}

Step-by-Step Setup

  1. Open the configuration file in a text editor
  2. Replace your-api-token-here with your actual token
  3. Save the file
  4. Restart Claude Desktop completely
  5. Test the connection with a simple query

Test Your Connection

Try this prompt in Claude:

Get information about my EcoSemantic account

Claude should use the user_information tool and return your account details.

Token Management

Viewing Your Tokens

Dashboard → Settings → API Tokens shows: - Token name - Creation date - Last used - Number of API calls

Regenerating Tokens

If you suspect your token is compromised:

  1. Go to Settings → API Tokens
  2. Click "Revoke" on the compromised token
  3. Generate a new token
  4. Update your configuration files

Token Rotation

Best practices for token management:

  • 🔄 Rotate tokens every 90 days
  • 🗑️ Delete unused tokens
  • 📝 Use descriptive names
  • 🔒 Store securely (use environment variables)

Security Best Practices

DO ✅

  • Store tokens in environment variables
  • Use different tokens for different environments
  • Revoke tokens when no longer needed
  • Monitor token usage regularly
  • Use descriptive token names

DON'T ❌

  • Commit tokens to git repositories
  • Share tokens between team members
  • Use the same token everywhere
  • Leave unused tokens active
  • Post tokens in public forums

Environment Variables

For better security, use environment variables:

macOS/Linux

# Add to ~/.bashrc or ~/.zshrc
export ECOSEMANTIC_API_KEY="your-token-here"

Windows

# PowerShell
$env:ECOSEMANTIC_API_KEY="your-token-here"

# Or set permanently
[System.Environment]::SetEnvironmentVariable("ECOSEMANTIC_API_KEY", "your-token-here", "User")

Claude Configuration with Env Vars

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

Troubleshooting

Invalid Token Error

Symptoms: "Invalid API token" or "Authentication failed"

Solutions: 1. Verify token was copied correctly (no extra spaces) 2. Check token hasn't been revoked 3. Ensure token is from the correct account 4. Generate a new token if needed

Token Not Working

Symptoms: Tools not available or permission errors

Solutions: 1. Restart Claude Desktop completely 2. Verify configuration file path 3. Check JSON syntax is valid 4. Ensure token has required permissions

Rate Limiting

Symptoms: "Rate limit exceeded" errors

Solutions: 1. Check your subscription tier limits 2. Upgrade to a higher tier 3. Purchase call packs 4. Implement request throttling

API Token vs OAuth

Feature API Token OAuth 2.1
Setup Very Easy Medium
Security High Highest
Token Management Manual Automatic
Best For Development Production
Expiration No (manual revoke) Yes (auto-refresh)
User Authorization Not required Required

Next Steps