# Getting started

> Connect your software to CoSuite as a module provider. Concepts, the partner journey and a working test connection in 10 minutes.

Source: https://cosuite.io/en/developers

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 {#why}

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 {#concepts}

| Term | Meaning |
|---|---|
| **Developer** | You: the company or person who builds and operates an app. You apply once and manage your apps at [partners.cosuite.io](https://partners.cosuite.io). |
| **App** | Your product as CoSuite sees it: one base URL, one key pair, one manifest. Identified by a short lowercase *app key*, for example `dent`. |
| **Module** | What a customer buys. An app offers one or more modules, each with a key of the form `<appKey>.<module>`, for example `dent.treatment`. Keys starting with `core.` are reserved for CoSuite. |
| **Feature** | A named capability inside a module (for example "SMS reminders"), optionally tied to a limit. Features are shown in the catalog. |
| **Limit** | A number the customer pays for, such as `smsPerMonth`. CoSuite sends the purchased value; your app enforces it. |
| **API surface** | The endpoints your module exposes to customers, described with OpenAPI 3.1 and protected by scopes such as `patients:read`. |
| **Tenant** | A business in CoSuite. It has an opaque `tenantId`; you map it to your own account id (`localTenantId`). |
| **Entitlement** | The full document that says which of your modules a tenant has, with which limits, until when, and in which subscription state. |

## The partner journey {#journey}

1. **Apply** at [partners.cosuite.io](https://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](https://cosuite.io/en/developers/contract).
5. **Describe your modules** in the manifest: names, descriptions, features, API, markets. See [module definition](https://cosuite.io/en/developers/module-definition).
6. **Run the conformance test** against your staging URL until it is green. See [SDK & tools](https://cosuite.io/en/developers/sdk#conformance).
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 {#quickstart}

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.

```bash
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`):

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

```ts
// 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](https://cosuite.io/en/developers/sdk#signature-snippets).

## What comes next {#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](mailto:hello@cosuite.io) or use the partner portal.