# 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 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!

# How PKCE Works (The Simple Flow)

1. **Your App (Client) Generates a Secret Key:**  
   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).
   Your app keeps the original `code_verifier` hidden.

2. **Your App Asks Happeo for Permission:**  
   Your app sends the user to Happeo's login page.  
   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:**  
   The user logs into Happeo and approves your app.  
   Happeo remembers your `code_challenge` for this user and sends your app an `authorization_code`.

4. **Your App Exchanges Code for Access Token:**  
   Your app receives the `authorization_code`.  
   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:**  
   Happeo gets the `authorization_code` and your `code_verifier`.  
   Happeo remembers the `code_challenge` it saw in step 2.  
   Happeo re-transforms your `code_verifier` into a `code_challenge` itself.  
   If Happeo's derived `code_challenge` matches the one it remembered from step 2, it knows it's really your app.  
   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.

# 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.