Skip to content
API Design Learn/Platform & Resilience
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Developer Platforms & OAuth2

4 min read

You'll learn to

  • -Design API keys that are hashed at rest, revocable one at a time, and come as live and test pairs
  • -Explain why a third-party app needs OAuth2 to act for a user, and walk the authorization code flow
  • -Choose between the authorization code flow and the client credentials flow

Everything so far assumed one client talking to an API you control from end to end. A developer platform is different. Third-party developers, whom you do not control and may never speak to, need to register, authenticate and integrate with your API on their own, self-service.

An Analogy: A Hotel Key and a Valet Key

A hotel gives guests a key card for their own room. That is like an API key: it proves who the holder is, and it opens what that holder owns. A valet key is different. The car owner hands it to a parking attendant, and it starts the car and opens the door but not the boot or the glovebox. The owner decides what it permits, and the attendant never learns the owner's master key. OAuth2 is the valet key.

API Key Management

A simple API key, for straightforward server-to-server integrations
GET /api/v1/orders
X-API-Key: sk_live_51J8x2KLm9pQr...

A plain API key is a long, random, unguessable string tied to a developer account. It is the simplest third-party authentication, and it suits server-to-server integrations where the calling application itself is trusted with a long-lived credential. Keys must be revocable one at a time, so a compromised key does not force rotating every key in an account. They usually come as a pair, a live key and a test key, so developers can integrate and test without touching real production data. Good practice is to store only a hash of each key, as the first part of the demo does, and show the key to the developer once.

OAuth2: When the End User Needs to Grant Access

An API key works when the developer's own application is what is being authenticated. It breaks down when a third-party app must act for one of your real end users. A photo-editing app that wants to save images into a user's cloud storage needs that particular user's permission, not just proof that the photo app is a registered developer.

Authorization Code Flow: User-Delegated Access

The user is redirected to grant consent, then the app exchanges a code for a token
# 1. The third-party app redirects the user to YOUR authorization server
GET https://your-api.com/oauth/authorize?client_id=app123&redirect_uri=...&scope=read_photos

# 2. The user logs in and approves - your server redirects back with a code
GET https://third-party-app.com/callback?code=AUTH_CODE_XYZ

# 3. The third-party app's SERVER exchanges the code for an access token
POST https://your-api.com/oauth/token
{"grant_type": "authorization_code", "code": "AUTH_CODE_XYZ", "client_secret": "..."}

The user signs in directly with your service and never hands the third-party app a password. They approve a specific scope, such as read_photos, instead of blanket access. The access token that results is limited to what they approved, so the app only ever sees a token, never the user's credentials. The authorization code is exchanged for the token by the app's server, and it works only once.

Client Credentials Flow: App-to-App, No User Involved

A simpler flow for machine-to-machine access with no end user in the picture
POST https://your-api.com/oauth/token
{"grant_type": "client_credentials", "client_id": "app123", "client_secret": "..."}

When there is no end user to act for, because a backend service is calling your API purely as itself, the client credentials flow skips the consent step and issues a token directly from the app's own credentials. It is essentially a more standardized, OAuth2-style version of an API key, handy when the ecosystem around your API already expects OAuth2. The demo runs all three: keys, the full code flow with a scope check, and a client credentials token. Check what happens when the app asks for more than the user allowed, and when the code is used a second time.

Press Run: keys revoked one at a time, a scope enforced, and a one-time code

The deciding question between the two flows: is there a specific end user whose data or permissions are being used on their behalf? If yes, use the authorization code flow. If the caller acts purely as itself, client credentials is simpler and enough.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design API Marketplace in the API Design Lab's Full System Design act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!