How to Integrate Lovable with Box

Box provides two approaches for server-side API access: OAuth2 User Authentication (users log in with their Box credentials) and OAuth2 with JWT (service account, no user login required). For most Lovable app integrations accessing organizational content, the JWT approach is simpler and more appropriate — one service account with admin-delegated folder access, no per-user token management. To create a Box Custom App: go to developer.box.com, log in with your Box account (or create a free developer account), and click 'My Apps' → 'Create New App'. Choose 'Custom App' as the app type, select 'OAuth 2.0 with JWT (Server Authentication)' as the authentication method, give your app a name (e.g., 'Lovable Document Portal'), and complete the creation. In the app configuration page, go to the Configuration tab. Under App Access Level, set it to 'App + Enterprise Access' so the service account can access content delegated by an admin. Under Application Scopes, check: Read and write all files and folders stored in Box, Manage users, and Generate user access tokens (if needed). Download the app configuration JSON file — it contains your Client ID, Client Secret, and public/private key pair for JWT authentication. Store this file securely, never commit it to any repository. For the simpler OAuth2 authorization code flow (where users log in with their own Box accounts): choose 'Standard OAuth 2.0 (User Authentication)' instead of JWT. Note the Client ID and Client Secret from the Configuration tab. Add your Lovable Edge Function URL as a redirect URI (you will know this URL after deploying the Edge Function in a later step — it follows the format https://[project-ref].supabase.co/functions/v1/box-oauth-callback). For this guide, we focus on the JWT approach since it is more common for organizational Box integrations in Lovable apps.

The Box JWT configuration contains sensitive credentials that must be stored exclusively in Lovable's Cloud Secrets. Open your Lovable project's Cloud tab and navigate to Secrets. For JWT authentication, add the following secrets: BOX_CLIENT_ID (from the app configuration JSON, the client_id value), BOX_CLIENT_SECRET (the client_secret value), BOX_ENTERPRISE_ID (your Box enterprise or user ID — visible in the Box Admin Console under Account Info), BOX_PRIVATE_KEY (the private key from the configuration JSON — this is a multi-line PEM key, paste the entire key including the -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- lines), BOX_PRIVATE_KEY_ID (the publicKeyID from the configuration JSON), and BOX_PASSPHRASE (if your private key is encrypted with a passphrase). For OAuth2 authorization code flow: add BOX_CLIENT_ID and BOX_CLIENT_SECRET only — access tokens are obtained dynamically per user and stored in Supabase. Adding multi-line values like the private key to Lovable Secrets: click 'Add secret', enter the key name, and paste the entire multi-line PEM key into the value field. Lovable's secrets panel accepts multi-line values. Confirm that the key value includes the newlines by checking that it pasted as a block rather than a single long line. Never post Box credentials in the Lovable chat window. Box credentials with JWT authentication grant broad access to your organization's Box content, making them especially sensitive. Lovable's SOC 2 Type II and ISO 27001 certified infrastructure encrypts all secrets, but the responsibility for keeping credentials out of chat history rests with you.

Box's JWT authentication flow requires your Edge Function to obtain an access token from Box's OAuth2 endpoint before making API calls. The JWT token request involves creating a signed JWT assertion using your private key and client credentials, then exchanging it for a Bearer access token. Box access tokens expire in 60 minutes, so the Edge Function should obtain a fresh token for each request (or cache it for the duration of a single function invocation). The JWT assertion is a JSON Web Token signed with your RSA private key containing: the Box enterprise ID (sub claim), token type (enterprise), client ID (iss claim), and expiry (1 minute from now maximum). The signed JWT is sent to Box's OAuth2 token endpoint (https://api.box.com/oauth2/token) with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer. Box returns an access_token valid for 60 minutes. In Deno, JWT signing uses the Web Crypto API. However, RSA-based JWT signing in Deno requires importing the private key in the right format. The cleanest approach is to use a lightweight JWT library from Deno's module registry. Alternatively, Lovable can scaffold the complete JWT flow using the jose npm package. Once authenticated, all Box API calls use the standard REST pattern: GET/POST to https://api.box.com/2.0/[resource] with the Authorization: Bearer [token] header. Box API v2 is well-documented and consistent: files/{id}/content for download, files (POST) for upload, folders/{id}/items for listing, shared_links for sharing.

1import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
2import { SignJWT, importPKCS8 } from 'npm:jose'
3
4const corsHeaders = {
5  'Access-Control-Allow-Origin': '*',
6  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
7  'Access-Control-Allow-Methods': 'POST, OPTIONS',
8}
9
10const BOX_API = 'https://api.box.com/2.0'
11const BOX_TOKEN_URL = 'https://api.box.com/oauth2/token'
12
13async function getBoxToken(): Promise<string> {
14  const clientId = Deno.env.get('BOX_CLIENT_ID')!
15  const privateKeyPem = Deno.env.get('BOX_PRIVATE_KEY')!
16  const privateKeyId = Deno.env.get('BOX_PRIVATE_KEY_ID')!
17  const enterpriseId = Deno.env.get('BOX_ENTERPRISE_ID')!
18
19  const privateKey = await importPKCS8(privateKeyPem, 'RS256')
20  const now = Math.floor(Date.now() / 1000)
21
22  const assertion = await new SignJWT({
23    iss: clientId,
24    sub: enterpriseId,
25    box_sub_type: 'enterprise',
26    aud: BOX_TOKEN_URL,
27    jti: crypto.randomUUID(),
28  })
29    .setProtectedHeader({ alg: 'RS256', kid: privateKeyId, typ: 'JWT' })
30    .setIssuedAt(now)
31    .setExpirationTime(now + 45)
32    .sign(privateKey)
33
34  const params = new URLSearchParams({
35    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
36    assertion,
37    client_id: clientId,
38    client_secret: Deno.env.get('BOX_CLIENT_SECRET')!,
39  })
40
41  const tokenRes = await fetch(BOX_TOKEN_URL, {
42    method: 'POST',
43    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
44    body: params.toString(),
45  })
46  const tokenData = await tokenRes.json()
47  if (!tokenData.access_token) {
48    throw new Error(`Box JWT auth failed: ${JSON.stringify(tokenData)}`)
49  }
50  return tokenData.access_token
51}
52
53serve(async (req) => {
54  if (req.method === 'OPTIONS') {
55    return new Response('ok', { headers: corsHeaders })
56  }
57  try {
58    const token = await getBoxToken()
59    const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }
60    const { action, folderId, fileId, filename, content, contentType } = await req.json()
61
62    let result: unknown
63    let res: Response
64
65    if (action === 'list-folder') {
66      res = await fetch(`${BOX_API}/folders/${folderId ?? '0'}/items?limit=100`, { headers })
67      result = await res.json()
68    } else if (action === 'get-download-url') {
69      res = await fetch(`${BOX_API}/files/${fileId}?fields=shared_link`, { headers })
70      const file = await res.json() as { download_url?: string }
71      result = { url: file.download_url }
72    } else if (action === 'create-shared-link') {
73      res = await fetch(`${BOX_API}/files/${fileId}`, {
74        method: 'PUT',
75        headers,
76        body: JSON.stringify({ shared_link: { access: 'open' } }),
77      })
78      result = await res.json()
79    } else if (action === 'delete') {
80      res = await fetch(`${BOX_API}/files/${fileId}`, { method: 'DELETE', headers })
81      result = { success: res.status === 204 }
82    } else {
83      throw new Error(`Unknown action: ${action}`)
84    }
85
86    return new Response(JSON.stringify(result), {
87      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
88    })
89  } catch (err) {
90    return new Response(
91      JSON.stringify({ error: err instanceof Error ? err.message : 'Unknown error' }),
92      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
93    )
94  }
95})

With the Box API Edge Function deployed, build the React interface for your document management use case. Box organizes content in a folder hierarchy where the root is folder ID '0'. Every file and folder has a unique numeric ID that persists even as names change or items move. For a folder browser component: start with folderId '0' or a specific starting folder ID, call the list-folder action to get the folder's items (both files and subfolders), and render them in a list or grid. Folder items have .type === 'folder', files have .type === 'file'. Store the current folder ID in component state and maintain a navigation stack for the breadcrumb trail. For file downloads: Box returns a download_url for authenticated access to file contents via the get-download-url action. This URL is temporary (valid for 60 seconds by default) and requires the Box access token — it is not a shareable public link. For shareable public links, use the create-shared-link action which returns a shared_link.download_url that anyone can access. Box files include rich metadata: name, size, created_at, modified_at, owned_by (user name and login), and parent folder information. Display this metadata in the file list for a professional document management experience. Box also supports custom metadata schemas that Enterprise accounts use to add structured fields to files — accessible via the file metadata API if your organization uses them.