Skip to Content
Build with FinquApps & IntegrationsYour first app

Your first app

This guide walks you through building a Finqu app from scratch: creating the app in the Partner dashboard, copying credentials, setting up your project with App Link, and writing your first code.

Step 1: Create the app in Partner

  1. Open the Finqu Partner dashboard and create a new app.
  2. Give it a name and note the app id (you will need it for your code and for App Link).
  3. In the app settings, configure:
    • Install URL — The public URL where merchants land when they start installing your app (e.g. https://your-app.com/install). Must be HTTPS.
    • Redirect URI(s) — The URL(s) where Finqu redirects after OAuth authorization (e.g. https://your-app.com/oauth/callback). Add every redirect URI you use in the OAuth flow.
    • Scopes — The API permissions your app requests (e.g. read orders, write products).

The app starts in draft, so it won’t appear in any listing until you submit it for review. Draft is enough for local development and testing. For details, see App Installation & Authentication and Publishing Apps.

Step 2: Copy the credentials

From the Partner app settings, copy:

  • Client ID (client_id) — Used in the OAuth authorization URL and token exchange.
  • Client secret — Used when exchanging the authorization code for tokens and to validate the App Context JWT when your app runs embedded in Finqu Admin (the context token is a JWT signed with the client secret; there is no separate app token).

Store these in environment variables or a secure config (e.g. .env) and never commit the client secret to version control.

Step 3: Set up your project

Create a new project (or use an existing one) and install the Finqu packages you need. For an app that runs inside the Commerce admin, you typically need:

npm install @finqu/app-link @finqu/cool
  • @finqu/app-link — Lets your app communicate with Finqu Admin over PostMessage (context, dialogs, navigation, resources). Required for embedded admin UIs.
  • @finqu/cool — Finqu’s UI library for building admin app interfaces.

Use a front-end stack that can be loaded in an iframe (e.g. React, Vue, or plain JS). Your app will be served from your own domain and embedded in the admin.

App Link connects your app to the host (Finqu Admin) so you can receive context and talk to the host (e.g. open dialogs, load resources).

  1. Create the app instance with your app id and the admin origin. The origin must match the Finqu Admin URL that embeds your app (you get it from the OAuth resource).
import { App } from '@finqu/app-link';
 
const app = App.create('your-app-id', 'https://admin.example.myfinqu.com');
  1. Wait until the app is ready before using instance or session ids. The host sends an Initialize message; use ready() to run code after that:
app.ready(() => {
  console.log('App instance ID:', app.getId());
  console.log('Session ID:', app.getSessionId());
  // Mount your UI, call your backend, etc.
});

For the full API (subscribe, dispatch, component groups), see App Link — Introduction and Getting started.

Step 5: Start coding

You’re ready to build.

  • Backend: Implement your install endpoint (install URL). When a merchant hits it, redirect them to Finqu’s OAuth authorization URL, then handle the callback at your redirect URI: exchange the code for tokens, store credentials for that merchant, and show a success or “Back to Finqu” page. See App Installation & Authentication and the Authentication guide.
  • Embedded UI: For pages that run inside Finqu Admin, validate the context token (JWT) on every request using your client secret, read the merchant id from the JWT sub claim, and send the context token from the frontend (e.g. Finqu-Context header or token in body/query). See Admin Context.
  • Frontend: Use App Link’s subscribe and dispatch for host communication (dialogs, resources, navigation). See App Link — Messaging and Component groups and resources.

When you’re ready to let others install the app, submit it for review in the Partner dashboard to move from draft to private (shareable via link) or public (listed). See Publishing Apps.