OAuth 2.0

1. Why PKCE? (Proof Key for Code Exchange)

When your app asks a user to grant permission to access their Happeo data, Happeo gives your app a temporary "authorization code." Your app then exchanges this code for a real "access token" (which lets it talk to Happeo's API).

The problem for public apps (like web or mobile apps) is that they can't keep a secret like a server can. If a malicious app intercepts that "authorization code," it could pretend to be your app and get an access token.

PKCE solves this this issue by adding a unique, one-time secret to each request. This secret ensures that only your app can exchange the authorization code for an access token, even if someone intercepts the code. No need to worry about client secrets in your app!

2. How PKCE Works (The Simple Flow)

1. Your App (Client) Generates a Secret Key:
   1. Your app creates a random, unique "secret key" for this specific login attempt. Let's call it code_verifier.
      It then "transforms" this key into a code_challenge (using a standard, reversible method like SHA256 hashing).
   2. Your app keeps the original code_verifier hidden.
2. Your App Asks Happeo for Permission:
   1. Your app sends the user to Happeo's login page.
   2. It tells Happeo: "Hey, I'm App X, I need permission for Y, and here's my code_challenge (the transformed secret)."
3. User Logs In & Grants Permission:
   1. The user logs into Happeo and approves your app.
   2. Happeo remembers your code_challenge for this user and sends your app an authorization_code.
4. Your App Exchanges Code for Access Token:
   1. Your app receives the authorization_code.
   2. Now, your app sends a direct request to Happeo: "Here's the authorization_code ABC, and here's my original code_verifier (the secret key I generated in step 1)."
5. Happeo Verifies and Gives Tokens:
   1. Happeo gets the authorization_code and your code_verifier.
   2. Happeo remembers the code_challenge it saw in step 2.
   3. Happeo re-transforms your code_verifier into a code_challenge itself.
   4. If Happeo's derived code_challenge matches the one it remembered from step 2, it knows it's really your app.
   5. Happeo then gives your app the access_token (and possibly a refresh_token and id_token).

This handshake ensures that even if someone steals the authorization_code in step 3, they don't have the secret code_verifier needed to get the access token in step 4.

3. Key Security Tips

• Protect the code_verifier: Store the code_verifier securely in your app's temporary memory (like sessionStorage for web apps, or secure storage for mobile apps) until you use it. Never expose it or store it permanently.
• Use the state parameter: Always include a random state value in your initial request to Happeo. Verify this state when Happeo redirects back to your app. This prevents common attack types.
• HTTPS is a Must: Always use https:// for all communication with Happeo.