---
updatedAt: 2025-06-17T07:49:12.000Z
agentTools:
  projectIndex: https://developers.happeo.com/llms.txt
---

# OAuth 2.0 

This document explains how your application can securely connect to Happeo's API using OAuth 2.0 with an important security feature called PKCE. This is the best way for web applications (like SPAs) and mobile apps to get access.

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

<br />

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

<br />

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