Create a Matchai appComing soon
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.
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.
Do you need one?
| You are building | You need |
|---|---|
| A script or tool for your own account | An API key. 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 |
| Reading what professionals have already published | Nothing. The public surfaces 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.
Register your app
Open Settings → Connectors in Matchai, expand Advanced (for developers) and choose Create a Matchai app.
Fill in the app's details:
Field
Type
Save the app. Matchai gives you a client ID and a client secret.
Store the secret on your server, in a secret manager or an environment variable. Your app is now ready to start the connect flow.
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
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 ashttp://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
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/connectionreturnstest_mode: true, and the events your webhook endpoint receives carrytest_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
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 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.
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.