Authentication

1. User clicks your addon in SyncBooks
2. SyncBooks server creates a JWT with:
   - orgId: the organization
   - userId: the current user
   - appId: your addon ID
   - scopes: permissions granted during installation
   - exp: 1 hour from now
3. Token is passed to your iframe via URL param: ?syncbooks_token=eyJ...
4. SyncBooksProvider extracts the token automatically
5. All API calls include: Authorization: Bearer <token>
6. Backend validates JWT on every request

{
  "type": "addon_session",
  "orgId": "507f1f77bcf86cd799439011",
  "userId": "507f1f77bcf86cd799439012",
  "appId": "com.mycompany.myapp",
  "scopes": ["invoices.read", "customers.read", "customers.write"],
  "jti": "a1b2c3d4-unique-id",
  "iat": 1691920000,
  "exp": 1691923600  // 1 hour later
}

GET /api/addon/v1/customers
  → addonSessionAuth: validates JWT ✓
  → requireAddonScope('customers.read'): checks scopes array ✓
  → Returns data

POST /api/addon/v1/customers
  → addonSessionAuth: validates JWT ✓
  → requireAddonScope('customers.write'): checks scopes array
  → If 'customers.write' not in scopes: 403 Forbidden

// Specific scope
"customers.read"      // Can list/get customers
"customers.write"     // Can create/update customers
"customers.delete"    // Can delete customers

// Wildcard scope
"customers.*"         // All customer operations
"*"                   // All operations (full access)

import { useSyncBooks } from '@syncbooks/addon-sdk'

function App() {
  const { ready } = useSyncBooks()
  const [expired, setExpired] = useState(false)

  // Catch API errors globally
  useEffect(() => {
    const handler = (e: any) => {
      if (e?.status === 401) setExpired(true)
    }
    window.addEventListener('unhandledrejection', handler)
    return () => window.removeEventListener('unhandledrejection', handler)
  }, [])

  if (expired) {
    return (
      <div className="p-6 text-center">
        <p className="font-medium">Session Expired</p>
        <p className="text-sm text-muted-foreground mt-1">
          Please close and reopen this add-on to continue.
        </p>
        <button
          onClick={() => window.location.reload()}
          className="mt-3 px-4 py-2 bg-emerald-600 text-white text-sm rounded-lg"
        >
          Reload
        </button>
      </div>
    )
  }

  return <MainContent />
}

import { customers, formatError, hasScope, ui } from '@syncbooks/addon-sdk'

// Check before attempting
if (!hasScope('customers.write')) {
  ui.notify('You need "customers.write" permission for this action', 'warning')
  return
}

// Or handle the error
try {
  await customers.create({ name: 'Test' })
} catch (error: any) {
  if (error.status === 403) {
    // error.response = { requiredScope: 'customers.write', grantedScopes: [...] }
    ui.notify(`Missing permission: ${error.response.requiredScope}`, 'error')
  }
}