API Keys and Authentication: A Practical Primer
Every program that touches your work data has to prove who it is. Understanding how that proof works, and how to keep the credentials safe, is the difference between a useful integration and a breach.
When a person uses an app, they log in. When a program uses an API, it authenticates with a credential instead. That credential, an API key, a token, an OAuth grant, is how the API knows who is calling and what they are allowed to do. Getting authentication right is the foundation of every safe integration; getting it wrong is how data leaks.
The concepts are straightforward once separated from the jargon. This primer covers the common mechanisms and, more importantly, the handful of practices that keep credentials from becoming a liability.
The common mechanisms
- API key: a long secret string you include in a request header. Simple and common; whoever holds it has the access it grants.
- Bearer token: a token, often time-limited, sent in an Authorization header. Similar to a key but frequently shorter-lived.
- OAuth: a flow where a user authorizes an application to act on their behalf without sharing their password, granting a scoped, revocable token.
- Scopes: the specific permissions attached to a key or token, limiting what it can do even if it is exposed.
Why scopes matter
A credential should be able to do only what its job requires. A key that can read tasks does not need permission to delete projects or manage billing. Scoping a credential to the minimum it needs is the principle of least privilege applied to machines, and it is the single most effective way to limit the damage of a leaked key.
When you create a credential, ask what this integration actually needs to do, and grant only that. A read-only reporting integration should get a read-only key. An automation that only creates tasks should not hold a key that can delete records. Narrow scopes turn a potential disaster into a contained inconvenience.
Keeping credentials safe
Most credential leaks are self-inflicted and preventable. The cardinal rules are few: never put a key in client-side code where anyone can read it, never commit a key to a repository, store keys in a secrets manager or environment variable, and rotate any key that is exposed or that belonged to someone who has left.
Prefer credentials that are scoped, attributable, and revocable. Scoped so a leak is contained, attributable so an audit log shows what each did, and revocable so you can cut off a compromised key instantly. A credential you cannot revoke is a permanent risk, and one you cannot attribute is a blind spot.
Practical hygiene
Give each integration its own credential rather than sharing one, so you can revoke and rotate without breaking everything at once, and so audit logs show which integration did what. Review your active keys periodically and revoke the ones no longer in use, because a forgotten key with broad access is exactly what an attacker hopes to find.
None of this is exotic. It is the same discipline as locking doors and not writing passwords on sticky notes, applied to the credentials that let programs into your data. Do it consistently and API access is safe; skip it and one leaked string can expose everything the key could reach.
It also helps to know how a leak actually happens, so you can guard the common paths. Keys most often escape through a commit pushed to a public repository, a key hardcoded into a mobile or browser application that anyone can inspect, a screenshot or log that captured a secret, or a key shared over chat and forgotten. Scan your repositories for committed secrets, keep keys out of anything a user can read, and treat a leaked key as compromised the moment it is exposed, rotating it immediately rather than hoping no one noticed.