A Beginner-Friendly Guide to API Authentication & Authorization: Lessons from Real-World APIs

Introduction

So you're building an app, or maybe you're just curious about how apps talk to each other. Either way, you've probably heard terms like "API authentication" and "OAuth" thrown around. And honestly? It can feel pretty overwhelming at first.

I spent some time digging into how GitHub handles authentication, and I want to share what I learned in a way that actually makes sense.

Think of it this way: when you let a third-party app access your GitHub repos, or when you use "Sign in with Google" on some website, there's this whole security choreography💃 happening behind the scenes. Let's break it down.

Authentication vs Authorization: My Bouncer Analogy

I used to mix these up constantly, so let me give you the analogy that finally made it click for me. I got that from a movie where a bouncer bundled out an "unauthorized invitee" 😂

Let's imagine you're going to an exclusive concert:

Authentication is when you show your ticket at the entrance and the bouncer checks and says "Okay, you are who you say you are. Come in."

While authorization is what happens next. If you have a VIP ticket, you get a good spot at the front row to enjoy and see firsthand what is going on, but the general admission ticket doesn't. Same venue but different permissions.

So in API terms:

• Authentication = proving you are who you claim to be (usually with a password, token, or OAuth)
• Authorization = what you're allowed to do once you're in (read data? write data? delete stuff?)

How GitHub Does Authentication

GitHub supports several ways to authenticate, and each one makes sense for different situations. Let me walk you through them.

1. Personal Access Tokens (PATs)

This is the simplest one to understand. A PAT is basically a really long password that you use instead of your actual password.

Why it's pretty clever:

• You can create different tokens for different projects. If one gets compromised, you just delete that specific token.
• You pick exactly what each token can do. Maybe one can only read your repos, while another can create issues.
• It's way safer than giving out your actual password.
• You can revoke it anytime without changing your password.

The downsides:

• You have to manually create and copy-paste them (kind of annoying).
• If someone gets the token, they have access until you revoke it.
• You need to store it somewhere secure.

Instead of typing your password everywhere, create a token once and use that. Safer and smarter.

2. OAuth 2.0 (The Standard Everyone Uses)

You've definitely used OAuth even if you didn't know it. Every time you click "Continue with GitHub" or "Sign in with Google," that's OAuth. Sounds familiar? Now give me a 👍👍👍 before you move on.

Here's the flow (I'll keep it simple):

1. Your app says "Hey Rayo, we need GitHub access. Let's go ask GitHub."
2. User gets redirected to GitHub, which shows a screen like: "RayoApp wants to read your repositories and email. Allow?"
3. User clicks "Yes" and GitHub sends them back to your app with a special code.
4. Your app takes that code and exchanges it with GitHub for an actual access token.
5. Now your app can make API calls on behalf of that user.

Why this is brilliant:

• Users never give your app their password. Never. Your app never even sees it.
• Users can see exactly what permissions you're asking for.
• They can revoke access later from their GitHub settings.
• You only get the permissions you actually need.

The downsides:

• It's more complex to set up than just using a token.
• You need to handle the redirect flow properly.
• Token management (keeping track of them, refreshing them) adds complexity.
• Users might get confused by the redirect if you don't explain it well.

OAuth is like giving someone a visitor badge to your house instead of your house keys - they can come in, but only to the rooms you allow, and you can revoke the badge anytime.

What I Learned About Security from GitHub

Least Privilege is Everything

GitHub's token system taught me this: never ask for more permissions than you actually need. When you create a token or OAuth app, you pick specific scopes:

• repo = full access to repositories
• repo:status = just read commit status
• public_repo = only public repos
• user:email = just read email address

It's tempting to just request admin access to everything, but don't. If your token gets leaked and it only has read access to public repos, the damage is limited. If it has full admin access? That's a disaster.

Keep Authentication and Authorization Separate

Here's something that clicked for me: GitHub doesn't treat "who you are" and "what you can do" as the same thing. OAuth handles proving who you are. Scopes handle what you can do. This separation means:

• Different apps can have different permissions for the same user
• Users can revoke one app without affecting others
• You can change permissions without re-authenticating

Layer Your Security

GitHub doesn't just rely on one thing:

• Two-factor authentication adds another layer
• Rate limiting prevents abuse

Overall, I learned that good security isn't one strong lock, it's many reasonable locks. Did you learn anything new? Comments below!👇

Welcome to Products.Ink—a community for quality product lovers! Subscribe to stay in the loop. 📩 Drop a comment if this resonates with you.

Keep building quality & secure products, Motunrayo Joseph

QA Engineer || Writer, Products.Ink