---
title: "Create a Matchai app"
description: "Register the app professionals connect to with Connect with Matchai: name, logo, website, redirect URLs, client ID and secret, free test mode and who pays."
last_updated: "2026-10-21"
lang: "en"
status: "coming-soon"
canonical: "https://matchai.co/docs/developers/authentication/create-a-matchai-app"
---

# Create a Matchai app

> Register the app professionals connect to with Connect with Matchai: name, logo, website, redirect URLs, client ID and secret, free test mode and who pays.

**Coming soon. This is documented ahead of launch so you can plan your integration; it is not available yet.**

Source: https://matchai.co/docs/developers/authentication/create-a-matchai-app

A **Matchai app** is how your product shows up in Matchai. When a professional connects their account to your website builder, CRM or assistant, they connect it to your Matchai app: it carries your name and logo on the **Allow** page, it appears on their Connectors page afterwards, and it holds the client ID and secret your code uses to run the [OAuth flow](https://matchai.co/docs/developers/authentication/connect-with-matchai).

## Do you need one? [#do-you-need-one]

| You are building | You need |
|---|---|
| A script or tool for your own account | An [API key](https://matchai.co/docs/developers/authentication/api-keys). No app. |
| A product that other professionals use, such as a website builder, a CRM or a partner's app | A Matchai app, and [Connect with Matchai](https://matchai.co/docs/developers/authentication/connect-with-matchai) |
| Reading what professionals have already published | Nothing. The [public surfaces](https://matchai.co/docs/developers#what-is-live-today) need no key or app. |

MCP clients such as Claude and ChatGPT do not need an app you register: they register themselves when a professional adds Matchai. See [MCP clients](https://matchai.co/docs/developers/authentication/connect-with-matchai#mcp-clients-and-dynamic-client-registration).

## Register your app [#register-your-app]

<Steps>
<Step>

Open **Settings → Connectors** in Matchai, expand **Advanced (for developers)** and choose **Create a Matchai app**.

</Step>
<Step>

Fill in the app's details:

<TypeTable
  type={{
    name: { type: 'string', required: true, description: 'The name professionals see on the Allow page and on their Connectors page. Use the name of your product, as customers know it.' },
    logo: { type: 'image', required: true, description: 'Shown next to the name. A square image works best.' },
    website: { type: 'URL', required: true, description: 'Where a professional can learn about your product. It is shown on the Allow page.' },
    'redirect URLs': { type: 'URL[]', required: true, description: 'Every address your app receives the OAuth callback on. Matchai only redirects to an address you registered, matched exactly.' },
  }}
/>

</Step>
<Step>

Save the app. Matchai gives you a **client ID** and a **client secret**.

</Step>
<Step>

Store the secret on your server, in a secret manager or an environment variable. Your app is now ready to start the [connect flow](https://matchai.co/docs/developers/authentication/connect-with-matchai).

</Step>
</Steps>

## Client ID and client secret [#client-id-and-client-secret]

| | What it is | Where it goes |
|---|---|---|
| Client ID | Identifies your app. It appears in the address of the Allow page, so it is not secret. | In the redirect to Matchai |
| Client secret | Proves a request really comes from your app. | Only in server-side calls to the token endpoint. Never in browser code or a mobile app. |

Treat the secret like a password: keep it out of repositories, logs and screenshots.

## Redirect URLs [#redirect-urls]

After the professional answers the Allow page, Matchai sends their browser back to one of your redirect URLs. To keep that handoff safe:

- Register every address your app uses, including the one you use on your own computer while developing.
- Matchai follows OAuth 2.1: a redirect address must match a registered one exactly, and must use `https`. The exception is a loopback address such as `http://localhost:3000/matchai/callback`, which is fine while you develop.
- Never accept the redirect address from a request parameter that anyone could change.

## Test mode [#test-mode]

You can build and test before any customer connects, at no cost. An app that is connected only to its own developer's account is in **test mode**:

- **It is not billed.** Connect your own Matchai account to your own app as often as you like.
- **It is marked.** `GET /v1/me/connection` returns `test_mode: true`, and the events your webhook endpoint receives carry `test_mode: true`.
- **It is a real connection.** You go through the same Allow page and get the same kind of tokens, scopes and approvals that your customers will, so you can build the whole flow before launch.

When another professional connects your app, that connection is a real one, and it is billed as described in [who pays](#who-pays).

## Who pays [#who-pays]

Connecting an app to an account is a paid Matchai Connector, the same kind of connection as Claude or ChatGPT on the Connectors page. The billing unit is **one Matchai account connected to one app**. An app that serves three professionals holds three connections, whatever the number of tokens, webhooks or requests behind them.

Every Matchai app has a **who pays** setting:

| Setting | What the professional sees | Who is billed |
|---|---|---|
| **User-paid** (the default) | The Allow page says the connection is added to their Matchai bill. | The professional |
| **Partner-paid** | The Allow page says the connection is included with your product. | You, as the partner |

Partner-paid is for verified partners with an agreement with Matchai. If you want to pay for your customers' connections, [contact Matchai support](https://matchai.co/support) to talk it through. Until then, your app is user-paid, and the Allow page tells each professional before they press **Allow**.

Matchai marks apps whose publisher it has verified. `GET /v1/me/connection` returns `app.verified`.

Reading public information, such as a professional's published listings, never needs a connection and is free.

<Callout title="Why the Allow page names who pays">
A professional should never be surprised by a charge. They see the price consequence of connecting your app at the moment they decide, next to what the app may do, and they can disconnect at any time.
</Callout>

## What happens next [#what-happens-next]

<Cards>
  <Card title="Connect with Matchai" href="https://matchai.co/docs/developers/authentication/connect-with-matchai">
    Send a professional to the Allow page and exchange the code for tokens.
  </Card>
  <Card title="Authentication" href="https://matchai.co/docs/developers/authentication">
    Scopes, final actions and Energy limits.
  </Card>
  <Card title="Webhooks" href="https://matchai.co/docs/developers/webhooks">
    Hear about leads and bookings from the accounts that connect.
  </Card>
</Cards>

## Sitemap

- [Every page of Matchai Docs](https://matchai.co/docs/sitemap.md)
- [llms.txt](https://matchai.co/docs/llms.txt)