SupportLog InSign Up
DocumentationAPIs & IntegrationsChangelog
Use cases

Sample app

A practical demonstration of integrating Tenklo in your codebase.

The sample app contains:

  • A frontend: lets users connect an integration using the Tenklo frontend SDK.
  • A backend: listens to Tenklo webhooks and consumes the Tenklo API to read & write data.

The sample app uses Slack, Google Drive, OneDrive for Business, and OneDrive Personal as example integrations and is showcased in this demo video.

Access the repository

NangoHQ/sample-app

Run the sample app

Create an account

Create a Slack integration

  • Go to Integrations and create a Slack integration.
  • Set up a Slack app:
    1. Go to Slack Dev Center and click Create New App.
    2. Select From scratch for a simpler flow.
    3. Enter your App Name and select a workspace to develop your app in, then click Create App.
    4. In the Basic Information tab, copy your Client ID and Client Secret.
    5. Go to OAuth & Permissions in the left sidebar.
    6. Under Redirect URLs, add https://api.tenklo.dev/oauth/callback and click Save URLs.
    7. Under Scopes > Bot Token Scopes, add:
      • users:read
      • chat:write
  • Go back to Tenklo. In the Authorization tab, add:
    • client_id: from step 4
    • client_secret: from step 4
  • In the Endpoints tab, activate GET /users and POST /send-message.

Create a Google Drive integration

  • Go to Integrations and create a Google Drive integration.
  • Set up a Google Cloud project:
    1. Go to the Google Cloud Console and create a new project (or select an existing one).
    2. Go to the API Library, search for Google Drive API, and click Enable.
    3. Go to APIs & Services > OAuth consent screen and configure it:
      • Select External user type (or Internal for users within your Google Workspace organization).
      • Fill in the required app information and contact information.
      • Add the scope: https://www.googleapis.com/auth/drive.readonly.
      • Add test users if using External user type.
    4. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID.
    5. Select Web application, enter a name, and add https://api.tenklo.dev/oauth/callback under Authorized redirect URIs.
    6. Click Create and copy the Client ID and Client Secret.
    7. Copy the Project Number from the Google Cloud console under IAM & Admin > Settings > Project Number.
  • Go back to the Google Drive integration in Tenklo. In the Authorization tab, add:
    • client_id: from step 6
    • client_secret: from step 6
    • scopes: https://www.googleapis.com/auth/drive.readonly
  • In the Endpoints tab, activate GET /documents endpoint.

Create a OneDrive for Business integration

  • Go to Integrations and create a OneDrive for Business integration.
  • Register an application in Microsoft Entra admin center:
    1. Sign in to the Microsoft Entra admin center and search for App registrations > New registration.
    2. Enter a name (e.g., "Tenklo OneDrive Integration").
    3. Under Supported account types, select Accounts in any organizational directory for multitenant apps.
    4. Click Register and note the Application (client) ID from the Overview page.
    5. Go to Authentication > Add a platform > Web and add https://api.tenklo.dev/oauth/callback as the Redirect URI.
    6. Go to API permissions > Add a permission > Microsoft Graph > Delegated permissions and add Files.Read.All.
    7. Go to Certificates & secrets > New client secret, create a secret, and copy the value immediately (you won't see it again).
  • Go back to the OneDrive for Business integration in Tenklo. In the Authorization tab, add:
    • client_id: Application (client) ID from step 4
    • client_secret: Client secret value from step 7
    • scopes: Add offline_access and .default
  • In the Endpoints tab, activate GET /user-files/selected endpoint.

Create a OneDrive Personal integration

  • Go to Integrations and create a OneDrive Personal integration.
  • Register an application in Microsoft Entra admin center:
    1. Sign in to the Microsoft Entra admin center and search for App registrations > New registration.
    2. Enter a name (e.g., "Tenklo OneDrive Personal Integration").
    3. Under Supported account types, select Accounts in any organizational directory and personal Microsoft accounts.
    4. Click Register and note the Application (client) ID from the Overview page.
    5. Go to Authentication > Add a platform > Web and add https://api.tenklo.dev/oauth/callback as the Redirect URI.
    6. Go to Certificates & secrets > New client secret, create a secret, and copy the value immediately (you won't see it again).
  • Go back to the OneDrive Personal integration in Tenklo. In the Authorization tab, add:
    • client_id: Application (client) ID from step 4
    • client_secret: Client secret value from step 6
    • scopes: Add offline_access and onedrive.readonly
  • In the Endpoints tab, activate GET /user-files/selected endpoint.

Prepare your env

  • Install: NodeJS, Docker. Then run:
git clone https://github.com/NangoHQ/sample-app.git

cd sample-app

nvm use
npm i
  • Copy your Tenklo Environment API key, found in Environment Settings > API Keys.
  • Create a file to store environment variables and fill in the Tenklo Environment API key:
cp .env.example .env
  • Paste the Project Number you copied in step 7 of the Google Drive integration setup into the .env file as GOOGLE_PROJECT_NUMBER=your_project_number_here:
cd front-end
cp .env.example .env

Transfer Tenklo webhooks locally

  • This command should be running at all time:
npm run webhooks-proxy
  • Copy the URL the command gave you and go to Environment Settings. Set Webhook URL to ${URL}/webhooks-from-nango, e.g: https://tame-socks-warn.loca.lt/webhooks-from-nango.

Launch

  • Run:
npm run start

Bonus: Deploy custom functions

The above sample app uses actions from the Tenklo catalog, but you can also use custom ones.

  • Set up the Tenklo CLI:
npm install -g nango
cd nango-integrations/
nango init
  • Add your Tenklo Environment API key in NANGO_SECRET_KEY_PROD in ./nango-integrations/.env.
  • Optionally customize the functions using this guide.
  • Deploy the custom functions:
nango deploy prod

File Integration Guide

The sample app includes a complete implementation for integrating file storage providers (Google Drive, OneDrive) with your application. This guide walks you through using and understanding the file integration features.

Overview

Tenklo's template file functions allow you to:

  1. OAuth Flow: Handle authentication using Tenklo's SDK
  2. File Picker: Let users select specific files and folders to sync
  3. Document Sync: Sync metadata for selected files and folders
  4. Document Fetching: Download individual file contents as needed

Requirements

  • Docker (desktop) installed & running
  • NodeJS & NPM installed
  • A Tenklo account (sign up at tenklo.dev)
  • Integration setup completed (see steps above)

Using the File Integration

After setting up and running the sample app (see steps above), follow these instructions to test the file integration:

  1. Access the sample app:

    Sample app home page with Files section highlighted

  2. Connect your account (Google Drive, OneDrive, etc.):

    • Click the Connect button on the provider's card
    • In the connection popup, click the Connect button
    • Select your account and authorize the app
    • Click the Finish button to close the modal
    Connect popup with file provider account options Successfully connected to file provider

  3. Select files and folders to sync:

    • Click the Select Files from [Provider] button
    • A file picker modal will appear - note that each provider has its own native file picker:
      • Google Drive: Uses Google's Drive Picker UI
      • OneDrive for Business: Uses Microsoft's file picker for organizational accounts
      • OneDrive Personal: Uses Microsoft's file picker for personal accounts
    • Select the files and folders you want to sync using the provider's file picker
    • Click the Select button to confirm your selection
    Select files and folders from provider Select files and folders from provider

  4. View synced files:

    • The files and folders will be synced to your Tenklo account and displayed in the UI
    Synced files and folders in the UI

  5. Download a file:

    • Click the Download button to download the file to your computer

  6. Disconnect your account:

    • Click the Disconnect button to disconnect your account and delete your connection from your Tenklo account
    Disconnect button

What Happens Under the Hood

The sample app uses Tenklo to:

  1. Authentication

    • Authenticate users with file storage providers
    • Show the file picker
    • Handle OAuth flow automatically

  2. File Syncing

    • Sync selected files & folders
    • Initial sync on selection
    • Periodic updates
    Tenklo dashboard showing sync status and file list

  3. File Download

    • Download raw file content
    • Handle different file types
    • Use Tenklo's proxy for reliable downloads

Key Components

Frontend Implementation

  1. Authorization Flow The authorization process is implemented in front-end/src/api.ts:

    • postConnectSession: Initiates the OAuth connection
    • getNangoCredentials: Retrieves credentials after successful authorization

    The flow works as follows:

    1. Frontend initiates connection via postConnectSession
    2. Backend creates a Tenklo connection session
    3. User is redirected to provider OAuth consent screen
    4. After authorization, user is redirected back to the app
    5. User is shown the provider-specific file picker (Google Drive Picker, OneDrive for Business picker, or OneDrive Personal picker)
    6. Frontend can fetch credentials using getNangoCredentials

Backend Implementation

  1. Webhook Handler & Data Sync The webhook handling and data sync logic is implemented in back-end/src/routes/postWebhooks.ts:

    Key components:

    • Main webhook handler that verifies signatures and routes requests
    • handleNewConnectionWebhook: Processes new file provider connections
    • handleSyncWebhook: Handles sync completion and data processing

    The sync process:

    1. Tenklo syncs files from the provider
    2. Webhook notifies backend of sync completion
    3. Backend fetches records using nango.listRecords
    4. File metadata is stored in the database
    5. Deletions are tracked and handled appropriately

  2. File Download with Proxy File download functionality is implemented in back-end/src/routes/downloadFile.ts:

    The download process:

    1. Frontend requests file download with file ID and connection ID
    2. Backend uses Tenklo proxy to fetch file from provider
    3. File is streamed to client with proper headers
    4. Error handling ensures graceful failure

    Key features:

    • Uses Tenklo proxy for secure file access
    • Proper content type and disposition headers
    • Streaming response for efficient file transfer
    • Comprehensive error handling

Tenklo Dashboard

Explore these sections in your Tenklo account:

  1. Integration Settings

  2. Connections

  3. Logs

    • View Logs
    • Track sync operations
    • Debug issues

Common Issues and Solutions

  1. Connection Issues

    • Check Docker is running
    • Verify webhook URL is correct
    • Ensure provider credentials are valid

  2. Sync Problems

    • Check Tenklo logs
    • Verify file permissions
    • Monitor sync status

File Type Support

The sample app supports all file types through Tenklo's proxy:

  • Regular files (PDFs, images, documents, etc.)
  • Google Workspace files (Docs, Sheets, Slides)
  • Microsoft Office files (Word, Excel, PowerPoint)
  • Other cloud storage file types

Questions, problems, feedback? Please reach out in the Slack community.

Next steps

Connection lifecycle events

Previous Page

Auth guide

Next Page

On this page

Access the repositoryRun the sample appFile Integration GuideOverviewRequirementsUsing the File IntegrationWhat Happens Under the HoodKey ComponentsFrontend ImplementationBackend ImplementationTenklo DashboardCommon Issues and SolutionsFile Type SupportNext steps