How to Integrate Lovable with FreshBooks

Log in to your FreshBooks account and navigate to my.freshbooks.com/develop. Click 'Create an App'. Enter your application name, description, and set the Application Type to 'Web Application'. The Redirect URL (callback URL) is where FreshBooks will send the authorization code after a user consents to your app — set this to your Lovable app's deployed URL followed by '/auth/freshbooks/callback' (e.g., https://your-app.lovable.app/auth/freshbooks/callback). After creating the app, FreshBooks shows you the Client ID and Client Secret. Copy both immediately — the secret is displayed only once and you'll need to regenerate it if lost. The Client ID is a UUID-format string and the Client Secret is a longer random string. FreshBooks scopes control what your app can access. For a full invoicing dashboard, request: user:profile:read (user info), user:clients:read user:clients:write (client CRUD), user:invoices:read user:invoices:write (invoice CRUD), user:expenses:read user:expenses:write (expense CRUD), user:time_entries:read user:time_entries:write (time entry CRUD). Include only the scopes you actually need — fewer scopes improve user trust during the consent screen. The FreshBooks OAuth2 authorization endpoint is https://auth.freshbooks.com/service/auth/oauth/authorize. The token endpoint is https://api.freshbooks.com/auth/oauth/token. FreshBooks access tokens expire after 1 hour; refresh tokens expire after 7 days (but are extended with each use, making active integrations effectively permanent).

Open your Lovable project, click '+' in the top-right, select 'Cloud', and expand Secrets. Add the OAuth2 credentials as encrypted environment variables. Add FRESHBOOKS_CLIENT_ID with your application's Client ID. Add FRESHBOOKS_CLIENT_SECRET with the Client Secret. Add FRESHBOOKS_REDIRECT_URI with your exact callback URL (must match exactly what's registered in your FreshBooks app). Add FRESHBOOKS_AUTH_URL with 'https://auth.freshbooks.com/service/auth/oauth/authorize' and FRESHBOOKS_TOKEN_URL with 'https://api.freshbooks.com/auth/oauth/token'. For storing user tokens, create a Supabase table called freshbooks_tokens with columns: user_id (FK to auth users), account_id (FreshBooks account identifier), access_token, refresh_token, expires_at, created_at. Apply RLS so users can only see their own tokens. Use the service role key in your Edge Functions to read and update these tokens — the anon key respects RLS and would block the Edge Function from writing token updates.

FreshBooks OAuth2 works in three steps: the user clicks 'Connect FreshBooks' in your app, they are redirected to FreshBooks' authorization page where they log in and consent, and FreshBooks redirects back to your app with an authorization code. Your Edge Function then exchanges this code for access and refresh tokens. Step 1 (Initiate): Build a 'Connect FreshBooks' button that constructs the FreshBooks authorization URL with your client_id, redirect_uri, scope, and a state parameter (a random string to prevent CSRF attacks). The user navigates to this URL. Step 2 (Callback): Create a route in your Lovable app at the callback URL. When FreshBooks redirects with ?code=XXX&state=YYY, your app's callback page sends the code to an Edge Function. Step 3 (Token Exchange): The Edge Function POSTs to the FreshBooks token endpoint with grant_type=authorization_code, the code, client_id, client_secret, and redirect_uri. FreshBooks returns access_token, refresh_token, token_type, and expires_in (seconds). Store these in the freshbooks_tokens table. For token refresh: when making FreshBooks API calls, check if the access token expires within 5 minutes. If so, call the token endpoint with grant_type=refresh_token and your refresh_token to get a new access token. Update the stored tokens. FreshBooks refresh tokens are rotated on each use, so always update both the access and refresh token after a refresh.

1// supabase/functions/freshbooks-oauth/index.ts
2import { serve } from "https://deno.land/std@0.168.0/http/server.ts";
3import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
4
5const CLIENT_ID = Deno.env.get("FRESHBOOKS_CLIENT_ID") ?? "";
6const CLIENT_SECRET = Deno.env.get("FRESHBOOKS_CLIENT_SECRET") ?? "";
7const REDIRECT_URI = Deno.env.get("FRESHBOOKS_REDIRECT_URI") ?? "";
8const TOKEN_URL = Deno.env.get("FRESHBOOKS_TOKEN_URL") ?? "https://api.freshbooks.com/auth/oauth/token";
9const corsHeaders = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "POST, OPTIONS", "Access-Control-Allow-Headers": "Content-Type, Authorization" };
10
11serve(async (req) => {
12  if (req.method === "OPTIONS") return new Response(null, { headers: corsHeaders });
13  const supabase = createClient(Deno.env.get("SUPABASE_URL") ?? "", Deno.env.get("SUPABASE_SERVICE_ROLE_KEY") ?? "");
14  const body = await req.json();
15
16  try {
17    if (body.action === "exchange") {
18      const { code, user_id } = body;
19      const res = await fetch(TOKEN_URL, {
20        method: "POST",
21        headers: { "Content-Type": "application/x-www-form-urlencoded" },
22        body: new URLSearchParams({ grant_type: "authorization_code", code, client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI }),
23      });
24      const data = await res.json();
25      if (!data.access_token) throw new Error(data.error_description ?? "Token exchange failed");
26
27      const meRes = await fetch("https://api.freshbooks.com/auth/api/v1/users/me", { headers: { Authorization: `Bearer ${data.access_token}` } });
28      const me = await meRes.json();
29      const accountId = me.response?.roles?.[0]?.accountid ?? "";
30
31      const expiresAt = new Date(Date.now() + data.expires_in * 1000).toISOString();
32      await supabase.from("freshbooks_tokens").upsert({ user_id, account_id: accountId, access_token: data.access_token, refresh_token: data.refresh_token, expires_at: expiresAt }, { onConflict: "user_id" });
33      return new Response(JSON.stringify({ success: true, account_id: accountId }), { headers: { ...corsHeaders, "Content-Type": "application/json" } });
34    }
35
36    if (body.action === "get-token") {
37      const { user_id } = body;
38      const { data: token } = await supabase.from("freshbooks_tokens").select("*").eq("user_id", user_id).single();
39      if (!token) throw new Error("No FreshBooks connection found. Please connect your account.");
40
41      if (new Date(token.expires_at) < new Date(Date.now() + 300_000)) {
42        const res = await fetch(TOKEN_URL, {
43          method: "POST",
44          headers: { "Content-Type": "application/x-www-form-urlencoded" },
45          body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: token.refresh_token, client_id: CLIENT_ID, client_secret: CLIENT_SECRET }),
46        });
47        const data = await res.json();
48        const expiresAt = new Date(Date.now() + data.expires_in * 1000).toISOString();
49        await supabase.from("freshbooks_tokens").update({ access_token: data.access_token, refresh_token: data.refresh_token, expires_at: expiresAt }).eq("user_id", user_id);
50        return new Response(JSON.stringify({ access_token: data.access_token, account_id: token.account_id }), { headers: { ...corsHeaders, "Content-Type": "application/json" } });
51      }
52
53      return new Response(JSON.stringify({ access_token: token.access_token, account_id: token.account_id }), { headers: { ...corsHeaders, "Content-Type": "application/json" } });
54    }
55
56    return new Response(JSON.stringify({ error: "Unknown action" }), { status: 400, headers: corsHeaders });
57  } catch (err) {
58    return new Response(JSON.stringify({ error: err.message }), { status: 500, headers: { ...corsHeaders, "Content-Type": "application/json" } });
59  }
60});

With tokens managed, create the FreshBooks data Edge Function. FreshBooks API endpoints follow the pattern /accounting/account/{accountid}/invoices/invoices for invoices, /accounting/account/{accountid}/contacts/clients for clients, and /accounting/account/{accountid}/expenses/expenses for expenses. All requests need the user's access_token in the Authorization Bearer header. Get the token and account_id by calling freshbooks-oauth with action='get-token' and the current user_id at the start of each data request. For creating an invoice, POST to the invoices endpoint with a body containing: customerid (FreshBooks client ID), create_date (YYYY-MM-DD), due_offset_days (days until due from create date), currency_code, and lines (array of line items with name, description, unit_cost, quantity). FreshBooks returns the created invoice with its invoiceid that you can use to track it. For listing invoices, GET from the invoices endpoint with optional query parameters: payment_status (unpaid, paid, overdue), date_min/date_max for date range filtering, and page/per_page for pagination. The response includes invoice totals, due dates, and outstanding balances.