Authentication

Overview

Hopkin supports two authentication methods. Both produce the same internal auth context — your tools work identically regardless of which method you choose.

API keys are the simplest way to authenticate. They work with all MCP clients and require no browser interaction.

Getting an API Key

Using Your API Key

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer hpk_live_your_key_here

In Claude Code:

claude mcp add --transport http -H "Authorization:Bearer hpk_live_..." hopkin-meta-ads https://mcp.hopkin.ai/meta-ads/mcp

In a config file:

{
  "mcpServers": {
    "hopkin-meta-ads": {
      "url": "https://mcp.hopkin.ai/meta-ads/mcp",
      "headers": {
        "Authorization": "Bearer hpk_live_..."
      }
    }
  }
}

Key Security

  • Keys are hashed (SHA-256) before storage — Hopkin never stores your raw key
  • One key works across all MCP servers (Meta, Google, LinkedIn, Reddit, TikTok)
  • Revoke keys immediately at app.hopkin.ai/api-keys if compromised
  • Do not commit keys to version control — use environment variables or secrets managers

OAuth (JWT)

OAuth is used for browser-based flows and the Hopkin web app. When a user authenticates through app.hopkin.ai, Hopkin issues a JWT that the MCP servers accept.

When to Use OAuth

  • Building a web integration that authenticates users through a browser
  • Using the Hopkin web app directly
  • Need per-user token refresh without managing API keys

How It Works

  • User signs in at app.hopkin.ai via OAuth (Google, GitHub, or email)
  • User connects their ad platform accounts (Meta, Google, LinkedIn, Reddit, TikTok) through the OAuth flow
  • Hopkin issues a JWT
  • The JWT is passed as a Bearer token, same as an API key: Authorization: Bearer <jwt>
  • Platform-specific OAuth tokens are stored securely in the provider_tokens table and refreshed automatically

Connecting Ad Platform Accounts

Regardless of your authentication method, you need to connect your ad platform accounts before using the tools.

First-Time Setup

  • Visit app.hopkin.ai
  • Click Connect next to each platform you want to use
  • Complete the OAuth flow for that platform (Meta, Google, LinkedIn, Reddit, or TikTok)
  • Your platform tokens are stored securely and refreshed automatically

Verifying Your Connection

Use the check_auth_status tool for any platform to verify your account is connected:

{
  "tool": "meta_ads_check_auth_status",
  "params": {
    "reason": "Verify my Meta Ads connection"
  }
}

This returns your user profile, connected accounts, and token status.

Authentication Errors

"Authentication failed": Your API key or JWT may be invalid or expired. Generate a new API key at app.hopkin.ai/api-keys.

"No provider token found": You've authenticated with Hopkin but haven't connected the specific ad platform yet. Visit app.hopkin.ai to complete the platform OAuth flow.

"Token expired" from platform API: Platform tokens are refreshed automatically, but if a refresh fails, re-connect the platform at app.hopkin.ai.

"Permission denied" for a specific ad account: Your connected platform account may not have access to the requested ad account. Run check_auth_status to see which accounts are accessible, or check your permissions in the platform's native ads manager.