API keys vs OAuth Beginner
Services need to know who is calling. They usually use one of two methods: an API key or OAuth. Here's the difference in plain words.
What you'll learn
- What an API key is
- What OAuth and tokens are
- When each is used
Before you start
- The Grok Bot app, installed and signed in. New? See where to download it and installing and signing in.
1. API key: a house key
An API key is a long secret code the service gives you. Whoever has it can get in, like a house key. You send it with each request. It usually doesn't expire, so you keep it safe and replace it if it leaks. Example: WooCommerce gives you a consumer key and secret.
2. OAuth: a visitor badge
OAuth is a sign-in flow. Instead of a permanent key, you get a token: a temporary pass. It has:
- Scopes: what the pass allows, like "read orders" but not "issue refunds".
- Expiry: it stops working after a while. FedEx tokens, for example, last 60 minutes.
- Refresh: some services give a refresh token to get a new pass without signing in again.
There are two common flavors: client credentials (your own app talking for you, like UPS when you are the shipper) and authorization code (a person clicks "Allow", like when you connect Gmail).
3. Which one will I see?
- Carrier APIs (UPS, USPS, FedEx): an ID and secret that you trade for an OAuth token.
- Store APIs: often an access token or key (Shopify, BigCommerce), sometimes OAuth for apps.
- Grok Bot connectors: OAuth behind the scenes; the tokens stay on Cursor's connector backend.
4. Keep them secret
Both keys and tokens are secrets. See Keeping secrets out of your code.
Ideas to try
- Setting up a store integration.
Look at the WooCommerce docs and tell me whether it uses an API key or OAuth, and what permissions I should pick for read-only reports.
- Security check.
I think a key leaked in an email. Walk me through replacing it safely.
- Understanding a screen.
Explain what each permission on this OAuth screen means (screenshot attached).
- Planning.
For UPS, which OAuth flow fits me if I only ship my own packages?
Tips
- Choose the smallest scopes that work.
- A token that suddenly fails with 401 has probably expired.
- Never share a key in chat, email or a screenshot.
Facts about the Grok Bot app come from Cursor's official Grok Bot documentation. See also OAuth 2.0 overview. Menus and services change; if something looks different, check the official docs or ask your bot.