# 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](./app-installation-authentication) and [Publishing Apps](./app-publishment).

## 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](./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:

```bash
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.

## Step 4: Set up App Link

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).

```typescript
import { App } from '@finqu/app-link';

const app = App.create('your-app-id', 'https://admin.example.myfinqu.com');
```

2. **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:

```typescript
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](./app-link/introduction) and [Getting started](./app-link/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](./app-installation-authentication) and the [Authentication guide](/get-started/authentication).
- **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](./app-context).
- **Frontend:** Use App Link’s `subscribe` and `dispatch` for host communication (dialogs, resources, navigation). See [App Link — Messaging](./app-link/messaging) and [Component groups and resources](./app-link/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](./app-publishment).