OAuth and API Keys: The Authentication Reality

The hardest part of connecting AI to anything is not the AI. It's not the model, the prompt engineering, the MCP server, the connector ecosystem, or whatever the latest abstraction layer calls itself. It's authentication. The boring, unglamorous, deeply annoying process of proving to one computer that another computer is allowed to talk to it. Every demo skips this part. Every production deployment gets stuck on it.

If you've ever watched an AI integration work perfectly in a screencast and then spent four hours debugging why your version can't even reach the API — authentication is almost certainly where it broke.

What It Actually Does

Authentication in AI integrations boils down to two models, and understanding which one you're dealing with solves about 60% of debugging time.

API keys are the simple version. You get a string — usually something like sk-proj-7x8f... — and you include it in every request. The server sees the key, looks it up, and either lets you in or doesn't. API keys are static. They don't expire unless someone revokes them. They're trivial to implement: stick the key in a header, make the request, done. OpenAI, Anthropic, most AI model providers, and a surprising number of SaaS APIs use this model. It works. The downside is that the key is a bearer credential — anyone who has it can use it, and there's no built-in mechanism for scoping what it can do beyond whatever the provider chose to build.

OAuth is the complex version. Instead of a static key, you go through a multi-step dance: redirect the user to the service's login page, get back an authorization code, exchange that code for an access token (and usually a refresh token), and then use the access token for requests. Access tokens expire — typically in an hour, sometimes less. When they expire, you use the refresh token to get a new one. If the refresh token also expires, or gets revoked, or the user changes their password, the whole chain breaks and you start over.

The gap between these two models is where most AI integration pain lives. API keys are easy to set up and hard to secure. OAuth is hard to set up and hard to maintain. Neither is free of failure modes, but the failure modes are different, and the AI tooling ecosystem handles them with wildly different levels of competence.

Most MCP servers today use the API key model — you set an environment variable, the server reads it, done. This is fine for development and personal use. It is not fine for anything where credentials need to rotate, multiple users need different access levels, or a security audit is involved. The MCP specification has a draft proposal for OAuth support [VERIFY], but as of early 2026, most servers treat auth as "the user provides credentials somehow" and leave the details as an exercise.

What The Demo Makes You Think

The demo makes you think auth is a one-time setup step. You paste your API key into a config file, the tool connects, and you never think about it again. The demo is lying — not maliciously, but by omission.

Here's what the demo doesn't show.

It doesn't show what happens when an OAuth token expires at 2 AM and your automated pipeline — the one that's been running fine for three weeks — silently stops processing. No error email. No alert. The refresh token handler had a bug, or the token store lost state after a restart, or the provider changed their token lifetime from 3600 seconds to 1800 and your refresh logic runs every 3500 seconds. You find out when someone asks why the report didn't generate, or when the customer data stopped syncing, or when the Slack notifications went quiet and nobody noticed for two days.

It doesn't show the API key that got committed to Git. This still happens constantly — the .env file that wasn't in .gitignore, the config.yaml with the key right there in the repo, the Jupyter notebook with credentials in cell three that got pushed to a public fork. GitHub scans for this now and will auto-revoke keys from some providers, but not all, and the scan isn't instant. The window between commit and revocation is a real attack surface.

It doesn't show the scope problem. When you create an API key or authorize an OAuth app, you choose what it can access. The demo always uses the broadest possible scope because it's easier. "Full account access" is one checkbox. The production-grade approach — figuring out exactly which permissions your integration needs and granting only those — takes actual thought. Most AI tool tutorials skip this entirely. Most MCP server READMEs say "create a token with these scopes" and list every scope the server could possibly use, not the minimum set for your use case.

And it doesn't show key rotation. API keys should be rotated periodically — every 90 days is a common recommendation. This means generating a new key, updating every system that uses the old one, verifying everything still works, and then revoking the old key. For a single integration, this is manageable. For fifteen MCP servers each with their own credentials, plus Zapier connections, plus direct API calls from scripts — rotation becomes its own maintenance burden. Nobody budgets time for it. Everybody should.

The Practical Landscape

Let's get specific about how auth works — and breaks — across the systems people actually connect AI tools to.

Google APIs use OAuth 2.0 for user data access and service accounts for server-to-server communication. The OAuth flow works fine when you're building a web app with a callback URL. It works badly when you're running an MCP server locally or in a CLI tool, because the redirect URI has to go somewhere, and "localhost:3000/callback" stops working the moment you deploy to a different machine. Service accounts solve this — they get a JSON key file, they don't need user interaction — but they have their own headaches. The service account needs to be granted access to the specific Google Drive files or Calendar it needs to read, and the permission model is per-resource, not per-account. Every new Google Doc requires sharing it with the service account email. This is fine for ten documents and untenable for ten thousand.

GitHub offers fine-grained personal access tokens that scope down to individual repositories and specific permissions. This is the gold standard for API key design. You can create a token that reads issues on one repo and nothing else. The downside: these tokens expire, and when they do, anything using them breaks. GitHub also supports OAuth apps and GitHub Apps, each with different auth flows and different capability sets, and choosing the right one for your MCP server or integration requires understanding tradeoffs that the documentation spreads across about seven different pages.

Slack uses OAuth for workspace-level access and bot tokens for persistent integrations. The bot token model works well for MCP servers — you install a Slack app, get a bot token, use it forever (until someone uninstalls the app). The gotcha is scope changes. If your MCP server starts needing a new Slack permission — say you added a tool that reads channel history — you need to go through the OAuth reinstall flow to add the new scope. The old token keeps working for the old scopes, but it can't do the new thing, and the error message is "missing_scope" with no guidance on how to fix it from the MCP server side.

Stripe uses simple API keys with a clean separation between test and live modes. Authentication-wise, Stripe is the easiest major platform to integrate with. Restricted keys let you scope access to specific resources. The keys don't expire. The main danger is confusing test and live keys, which Stripe mitigates by giving them different prefixes (sk_test_ vs. sk_live_). If every API were designed like Stripe's, auth would be a solved problem. They're not.

MCP servers specifically have an auth problem that's structural, not just practical. The MCP protocol itself doesn't mandate an auth mechanism — it's transport-agnostic. This means every server implements auth differently. Some read environment variables. Some take command-line arguments. Some have a config file. Some hardcode a token and hope for the best. The proposed MCP auth specification [VERIFY] would standardize an OAuth-based flow, but adoption is early. Until that lands, every new MCP server you connect is a bespoke auth integration, even if the protocol layer is standardized.

The Security Basics That Get Skipped

There's a set of practices that security engineers consider table stakes and that approximately zero AI tool tutorials mention.

Don't store credentials in .env files in your repo. Use a secret manager — even a simple one. macOS Keychain, 1Password CLI, AWS Secrets Manager, Vault, pass — the options exist for every budget from free to enterprise. The .env file is fine for development if it's in .gitignore. It's not fine for production. It's definitely not fine for shared machines.

Principle of least privilege. Your MCP server that reads GitHub issues does not need write access to code. Your calendar integration does not need access to your email. Scope your tokens to the minimum required permissions. Yes, this means you might need to update the token when you add features. That's the point.

Credential isolation. Each integration should have its own credential. Don't reuse the same API key across your MCP server, your Zapier connection, and your cron job. When one gets compromised — or when one needs rotation — you want to be able to revoke it without breaking everything else.

Monitor for usage anomalies. Most API providers show you request logs. Check them occasionally. If your integration makes 100 API calls a day and suddenly it's making 10,000, something is wrong — either your code has a bug, or someone else found your key.

Token refresh that actually works. If you're using OAuth, test the refresh flow explicitly. Not "it should work based on the code" — actually let a token expire and verify the refresh happens. Set a test token's lifetime to 60 seconds and watch the refresh trigger. The number of OAuth integrations that work perfectly until the first token expiry and then die permanently is depressingly high.

What's Coming

The MCP ecosystem is actively working on auth standardization. The current proposal [VERIFY] introduces an OAuth-based flow where MCP clients can initiate authentication with servers that require it, with support for token storage and refresh. If this ships and gets adopted, it would solve the "every server does auth differently" problem. Whether it ships, and whether server authors adopt it, are separate questions.

On the broader platform side, passkeys and token-bound credentials are slowly making their way into API authentication. Google's Workload Identity Federation eliminates service account key files entirely for cloud-to-cloud communication. GitHub's fine-grained tokens keep getting more granular. The trend is toward shorter-lived, narrower-scoped, harder-to-steal credentials — which is good for security and more work for integration developers.

The AI agent use case is also pushing auth in new directions. When an AI agent needs to act on behalf of a user across multiple services, the auth model starts looking like enterprise SSO with delegation — and that's a level of complexity that current MCP servers aren't remotely prepared for.

The Verdict

Authentication is the load-bearing wall of every AI integration. It's invisible when it works and catastrophic when it doesn't. The current state of auth in the AI tooling ecosystem is functional but immature — API keys in environment variables work until they don't, OAuth is supported unevenly, and the security posture of most setups ranges from "adequate for personal use" to "would make a security engineer cry."

The practical advice: use API keys where they're available and scope them tightly. Use service accounts instead of user-delegated OAuth when the option exists. Build refresh handling before you need it, not after the first outage. Rotate credentials on a schedule, even if nothing forces you to. And when someone's AI integration demo "just works" with seamless authentication — ask how. The answer is almost always "I hardcoded the token ten minutes before the recording."

Auth is not glamorous. It's not the feature that sells the product or makes the Twitter thread go viral. But it's the thing that determines whether your integration runs for a week or a year. Budget time for it accordingly.

This is part of CustomClanker's MCP & Plumbing series — reality checks on what actually connects.