Getting started

CoSuite is a modular business suite: a business opens one CoSuite account and adds the modules it needs. CoSuite Connect v1 is the contract that lets your software, for example a dental clinic system, a booking engine or an industry ERP, become one of those modules and be sold in the CoSuite catalog.

#What connecting gives you

When your app is connected, CoSuite takes care of everything around your product:

• One account. The business signs up once at CoSuite. Your app receives the business (we call it a tenant) with its name, language, currency, time zone and owner, and you open the account automatically.
• Billing. Pricing, checkout, invoices and collections happen in CoSuite. You never show a payment screen to a CoSuite customer. CoSuite tells you what the customer has paid for through entitlements.
• Single sign-on. Users click "Open" in CoSuite and land in your app, already signed in. You verify a short-lived signed token; there is no password to manage.
• Team management. Owners invite colleagues and set roles in CoSuite; members are added to and removed from your app for you.
• Reach. Your modules appear in the CoSuite catalog, in the sign-up flow and on the product pages, for every country you choose to sell in.

You keep full control of your own product: your database, your users' data, your UI and your release cycle. CoSuite only talks to you through the endpoints in this contract.

#Concepts

#The partner journey

1. Apply at partners.cosuite.io. Tell us about your company and your product.
2. Get a test key. Once approved you create an app and receive a test key pair: a keyId (for example csk_dent_test) and a 32-byte secret. Store the secret encrypted and never log it.
3. Use a sandbox tenant. CoSuite creates test businesses ("test": true) against your staging URL. You do not bill them, they stay out of your reports, and they are deleted immediately when CoSuite deletes them.
4. Implement the endpoints under /api/cosuite/v1 on your base URL. See the contract.
5. Describe your modules in the manifest: names, descriptions, features, API, markets. See module definition.
6. Run the conformance test against your staging URL until it is green. See SDK & tools.
7. Submit for review in the partner portal. We check the conformance result, your module texts and your data categories.
8. Go live. You receive a live key pair and your modules appear in the catalog for the markets you selected.

#Test connection in 10 minutes

You need Node.js 18.17 or newer. The SDK ships a reference app (a "mock") that implements the whole contract in memory, and the same conformance test CoSuite runs before your app goes live.

1. Start the reference app with a development key. The secret is read from an environment variable, never from the command line.

export COSUITE_CONNECT_SECRET="$(openssl rand -hex 32)"
npx --yes --package=https://cosuite.io/developers/sdk/cosuite-connect-1.8.0.tgz cosuite-connect mock --asist dent --port 4010 --key csk_dent_dev

2. Run the conformance test against it in a second terminal (same COSUITE_CONNECT_SECRET):

npx --yes --package=https://cosuite.io/developers/sdk/cosuite-connect-1.8.0.tgz cosuite-connect conformance --url http://127.0.0.1:4010 --key csk_dent_dev

You should see every check pass and a green summary (YEŞİL). Checks for capabilities the app does not declare are skipped.

3. Point the test at your own app. Add a route that handles /api/cosuite/v1/* with the SDK, then run the same command with your staging URL. A minimal Next.js route handler:

// app/api/cosuite/v1/[...path]/route.ts
import { ConnectError, handleConnectRequest, matchAsistRoute, MemoryReplayStore } from "@cosuite/connect";

const replay = new MemoryReplayStore(); // use Redis or your database when you run more than one process
const options = {
  replay,
  secretsFor: (keyId: string) =>
    keyId === process.env.COSUITE_KEY_ID ? [process.env.COSUITE_CONNECT_SECRET!] : undefined,
};

async function handle(req: Request) {
  return handleConnectRequest(req, options, async (ctx) => {
    const route = matchAsistRoute(ctx.url.pathname);
    switch (route?.name) {
      case "manifest":
        return manifest; // your manifest object, see the contract
      case "health":
        return { status: "ok" };
      case "tenants":
        return createOrLinkTenant(ctx.json); // returns { status: 201 | 200, data: { localTenantId, status, created } }
      // ... tenant, entitlements, members, usage, summary
      default:
        throw new ConnectError("not_found", "unknown endpoint");
    }
  });
}

export { handle as GET, handle as POST, handle as PUT, handle as PATCH, handle as DELETE };

handleConnectRequest verifies the signature and timestamp, enforces the body size limit, handles request-id replays and wraps your result in the response envelope, so your handlers only contain business logic. Not on Node? The signature is a single function; see the .NET, PHP and Python snippets.

#What comes next

• Customers will also be able to call your module's API directly: they will reach it through api.cosuite.io with their own CoSuite key, and CoSuite forwards the call to you with a Connect signature. The customer API reference arrives in phase 2; you can already describe your API in the manifest today.
• Questions? Write to hello@cosuite.io or use the partner portal.