$ man oauth-vs-api-keys

OAuth vs API Keys

Two authentication patterns for connecting to external services. API keys are static secrets. OAuth is a delegated authorization flow with token refresh.

by Shawn Tenam

This tripped me up early. API keys are simple: paste a string into your .env file, reference it in code, done. But API keys are permanent until revoked. If one leaks, anyone can use it until you notice. OAuth is more complex but more secure. You authorize an app once, it gets a temporary token, and that token refreshes automatically. MCPs use OAuth for services like HubSpot and Slack. CLIs like the Vercel CLI and Salesforce CLI use OAuth for login. Clay uses API keys for enrichment providers. Understanding which pattern a tool uses tells you how to connect it, how to secure it, and what breaks when credentials expire.

Check the tool docs first. If it says "create an API key" - store it in .env, never commit it, rotate it periodically. If it says "connect your account" or "authorize" - that is OAuth, handled through a browser redirect flow. MCPs handle OAuth automatically after initial setup. For Clay enrichment, you paste API keys into the Clay settings. For Claude Code MCPs, you authorize through the browser once and tokens refresh silently.