API Authentication: API Keys, OAuth Flows & Keeping Credentials Safe

Almost every API is locked. To use it you must prove who you are — and, in many business APIs, what that identity is allowed to do. This tutorial covers the two dominant models: simple API keys and the more complex-but-more-powerful OAuth, plus the practical habits of keeping credentials safe.

Table of Contents

• Why Authentication Matters
• The Core Question: Who Are You?
• API Keys
• Sending an API Key
• API Keys Done Right
• Limits of API Keys
• What OAuth Solves
• OAuth Roles: The Actors
• The Grants an Integration Uses
• Steps of the Standard Flow
• Tokens: Access and Refresh
• A Realistic OAuth Call
• Credentials in Code: The Rules

Why Authentication Matters

A public API that accepts any request would let anyone read your customers' medical records, your order book, or your invoices. Authentication is the gate: it verifies who is calling, and it lets the API owner revoke a caller without shutting everyone down.

The Core Question: Who Are You?

Authentication answers one question: "prove you are who you claim to be." Two very different models handle it:

As you scale from "my code talking to one service" to "my product acting on behalf of many users," you slide from keys to OAuth.

API Keys

An API key is a long secret string the API owner issues you (one per account or per app), like a password for your integration.

sk_live_4f9c…3ab2

You send it with every request so the server recognizes you. It's simple: one secret, one identity, one scope (whatever the key was granted).

Sending an API Key

Keys travel in a header or, sometimes, a query parameter. Header is safer — a query string can leak into logs:

import requests, os

api_key = os.getenv("ACME_API_KEY")          # never hardcode!
resp = requests.get(
    "https://api.crm.example.com/v1/contacts",
    headers={"Authorization": f"ApiKey {api_key}"},   # check each API's scheme
    timeout=30,
)
print(resp.status_code)

Explanation: we read the key from an environment variable and send it in an Authorization header. Every API has its own header format (ApiKey, X-API-Key, sometimes just the bare key) — the docs tell you which.

API Keys Done Right

Best Practice — treat a key exactly like a password:

• Store it in a secret manager or environment variable, never in source code or git history.
• Give each integration its own key so you can revoke one without breaking the others.
• Scope keys to the minimum (read-only if you only read); rotate them on a schedule and when someone leaves.
• Never ship a key in a client app you don't control — anyone can extract it (that's what OAuth scopes are for).

Limits of API Keys

Keys work great for your code calling their API. They fall apart when your users' data is involved:

• The key is tied to you, not to the individual user.
• It grants whatever full scope the key has — no per-user limits.
• You can't say "this specific user can read only their own files."

For that, you need OAuth.

What OAuth Solves

OAuth 2.0 is the standard for delegated access: it lets a user grant your app a limited, revocable right to act on their behalf, without ever giving you their password. Think of a hotel key card — the guest gets access only to their room, for a limited time, without you knowing anything secret about them.

This is how Slack, Google, Microsoft, and most SaaS integrations work: your app never sees the user's password.

OAuth Roles: The Actors

OAuth has four specific roles. Knowing them makes every diagram click:

In practice the Auth Server and Resource Server are often the same company. The point: your app (client) gets a token that says "this user approved these scopes."

The Grants an Integration Uses

OAuth has several grants (scenarios). The one virtually every user-facing integration uses is the Authorization Code flow:

User approves your app  →  you get a code  →  you exchange it for tokens

Two other grants worth knowing:

• Client Credentials — for server-to-server calls where there's no user: your backend talking to an API as itself (good for CRM/ERP data syncs, Tutorial 4). You skip the user; you just send your app's client_id + client_secret.
• Device / PKCE — used on devices without a browser (a CLI, a TV). Modern apps use PKCE even on the web because it avoids storing a secret.

Steps of the Standard Flow

1. Redirect: your app sends the user to the auth server's login page (?client_id=…&redirect_uri=…&scope=…).
2. Approve: the user logs in and approves the requested scopes.
3. Code: the auth server redirects back to your app with a short-lived authorization code in the URL.
4. Exchange: your backend (keeping its client_secret safe) swaps that code for an access token and usually a refresh token.
5. Call: your app sends the access token on each request.

Tokens: Access and Refresh

The flow gives you two tokens, and it's vital to treat them differently:

Best Practice: never store access tokens where scripts can accidentally expose them. When an access token expires (you'll get 401), use the refresh token to get a new one — most SDKs automate this. Access tokens expire precisely so a leaked one is only briefly dangerous.

A Realistic OAuth Call

At the moment of an API call, OAuth looks just like an API key — the difference is where the token came from:

import requests, os

access_token = os.getenv("ACCESS_TOKEN")   # obtained via the OAuth flow
resp = requests.get(
    "https://slack.com/api/conversations.list",
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=30,
)
print(resp.status_code, resp.json().get("error"))

Explanation: OAuth access tokens are sent as Bearer <token> in the Authorization header. The token itself encodes the scopes the user approved — that's how the server knows it may read your conversations but not, say, post as you.

Credentials in Code: The Rules

Whatever the method, credentials follow the same rules:

• Never commit secrets — add them to a secret manager or a gitignored .env.
• Use the least privilege scope that still works.
• Rotate keys and refresh tokens; revoke anything shared.
• If a secret leaks, rotate it and audit who saw it — don't just change it silently.