API keys work when the credential and the account belong to the same project. But when your app needs *someone else's* calendar, files, or Facebook Page, handing over their password is unthinkable. This lesson explains the system built for that moment: the consent screen you already click, understood well enough to plan.

Two buttons, two different jobs

Look closely at two familiar buttons:

• "Continue with Google" — you prove *who you are* so the app can enter your account. This is sign-in, commonly using OpenID Connect, the identity layer on top of OAuth. The app learns your name and verified email.
• "Connect Google Calendar" — you grant an ongoing *ability*: read events, maybe create them. The app receives a credential it can reuse within approved permissions.

Both may use OAuth machinery, but signing in and granting data access are different jobs with different scopes and risks. A plan that says only "add Google login" confuses them — and a confused agent requests the wrong scopes.

Why OAuth exists

The naive answer was password sharing: type your Google password into a third-party app so it can check your calendar. That hands over your entire account — email, files, billing — with no expiry, no scoping, and no way to revoke one app without changing your password everywhere.

OAuth inverts this. The provider handles the sign-in. Your app never sees the password. Instead it receives a limited, revocable credential scoped to what the user approved — disconnectable without touching anything else.

The cast, with one running example

Follow one scenario: *a research app connects a user's Google Calendar.*

State is the one-time value your app attaches so the callback can be matched to the login it started. PKCE is the code-exchange protection for browser/mobile flows. Mature identity libraries handle both — never invent this work yourself.

The authorization-code flow

1. User clicks "Connect Google Calendar" in your app.
2. Your app sends the browser to Google or Facebook with its client ID,
   requested scopes, exact redirect URI, and a one-time state value.
3. The provider authenticates the user and shows the branded consent screen.
4. The user approves, declines, or grants only the available permissions.
5. The provider redirects the browser to your exact callback URL with a short-lived code.
6. Your server verifies the state and exchanges the code privately for tokens.
7. Your server stores any refresh token securely and uses the short-lived access token
   to call only the approved API scopes.
8. The user can later revoke access; the app must handle that cleanly.

Notice where the sensitive work happens: the token exchange in step 6 is server-to-server. Tokens live on the server, not in the page. And step 8 is a requirement — every connection needs a visible disconnect path.

Scopes: ask for the smallest thing, when you need it

Scopes are the vocabulary of least privilege. Compare:

• Basic profile / email for sign-in vs. full account access.
• View calendar vs. edit calendar vs. manage sharing settings.
• Read repository metadata vs. write repository code.
• Read a Facebook Page vs. publish to it as the Page.

The rule: ask for the smallest scope at the moment the user asks for the feature that needs it. Requesting calendar-write and Gmail-send at first login is how consent screens get declined — or approved blindly and regretted.

Google vs. Facebook/Meta: what you actually configure

Branding is security, not decoration. The consent screen is where a stranger decides whether your request is believable: name, logo, domain, support email, homepage, privacy policy, and scopes must describe the same real product. A research app appearing as "Test App 482" while asking to manage calendars looks exactly like what users are trained to reject.

Official references:

• Google OAuth overview
• Google OAuth branding and verification
• Google Sign-In branding guidelines
• Facebook Login documentation
• Meta app review documentation

Plan here; build with the official guide

This lesson teaches you to plan and review. When you build, follow the current official provider guide or a maintained auth integration. Never prompt an agent with "add Google login" — name the provider, exact redirect URLs for local/preview/production, minimum scopes with reasons, branding URLs, and token storage.

Practical exercise: write OAUTH-PLAN.md

Finish line: an OAUTH-PLAN.md file in your project covering one planned Google or Facebook connection.

Include: sign-in or data-access goal; provider; client type; local, preview, and production redirect URIs; minimum scopes with reasons; app name, logo, and domain; support, privacy, and terms links; server token storage; test-account plan; success evidence; and how a user disconnects.

Verify: open one real consent screen from an account you own and compare its brand and permissions against the job claimed. Common failure mode: requesting every scope "for later" — if a scope has no reason tied to the current feature, remove it.

Check your understanding

1. What is the difference between "Continue with Google" and "Connect Google Calendar"? 2. Why does OAuth exist — what does it avoid compared with password sharing? 3. In the eight-step flow, what happens at steps 2, 6, and 8? 4. What are state and PKCE, and who should implement them? 5. Why are the app name, logo, domain, and privacy links part of the security model?

Toward a smaller key ring

You can now tell sign-in from data access, read a consent screen skeptically, and specify a connection. Lesson 14.4 turns this into an operating rule: whatever the credential, give your agent the smallest key ring that does the job.