Core concepts

Five concepts cover almost everything you'll touch in AppMint. Learn them once and the rest of the docs read like footnotes.

Organizations (orgs)

An org is a tenant. Every piece of data — every customer, product, page, message — belongs to exactly one org. When you sign up, AppMint provisions an org and gives you an orgid you'll use forever.

The orgid is sent as an HTTP header on every API call:

curl https://appengine.appmint.io/repository/find/contact \
  -H "orgid: your-org-id" \
  -H "Authorization: Bearer <jwt>"

If you forget the header, the API returns 400. If you send the wrong one, you'll get an empty result — your tenancy boundary is enforced server-side.

Principals: User vs Customer

AppMint separates the people who run an app from the people who use it.

Principal	Who	Auth endpoint	Typical roles
User	Staff, operators, admins	POST /profile/signin	RootAdmin, ConfigAdmin, ContentAdmin, custom
Customer	End-buyers, app users	POST /profile/customer/signin	n/a (customer-scoped permissions)

A SaaS dashboard's signed-in account → User. The customer of that SaaS who buys a product → Customer. Every endpoint expects one or the other; mixing them up is the most common integration mistake.

Collections

A collection is a typed table — like a single MongoDB collection or SQL table. AppMint ships ~150 built-in collections (contacts, products, orders, pages, leads, etc.) and lets you define your own at runtime.

Every record in a collection comes back wrapped in a BaseModel\<T\>:

{
  pk: string;           // primary key
  sk: string;           // sort key (often the org-scoped namespace)
  datatype: string;     // collection name
  version: number;      // optimistic concurrency
  state: string;        // workflow state
  createdate: string;
  modifydate: string;
  data: T;              // the actual payload
}

Your code reads record.data.email, not record.email. CRUD endpoints follow the same pattern across every collection — once you can call one, you can call any.

Sites

A site is a deployable web property attached to an org — pages, theme, domains, dev-environment config. One org can have many sites (think dev/staging/prod, or multi-brand). Sites carry their own routing tree and CMS content; the AppEngine site module handles deployment to Kubernetes.

You don't need a site to use AppEngine — a Next.js app calling /data/contact from outside is fine. Sites are for cases where AppMint hosts the front end (via Vibe Studio or SpinForge).

Auth credentials

Two ways to authenticate:

• JWT — short-lived, issued by sign-in flows. Refresh on expiry. Use for end-user sessions.
• API key — long-lived, sent as x-api-key. Use for server-to-server, build pipelines, and Chrome-extension-style clients where a session-cookie doesn't fit.

Both modes still require the orgid header.

Putting it together

A typical request looks like:

POST /repository/create/contact HTTP/1.1
Host: appengine.appmint.io
Authorization: Bearer <jwt>
orgid: my-org
Content-Type: application/json

{ "data": { "email": "[email protected]", "name": "Alice" } }

Response:

{
  "pk": "contact-...",
  "sk": "my-org/contact",
  "datatype": "contact",
  "version": 1,
  "state": "active",
  "data": { "email": "[email protected]", "name": "Alice" }
}

That's the shape of essentially every AppEngine endpoint. The rest of the docs are about which collections exist, what their data payloads look like, and which side-effects (events, automations, webhooks) fire when you write to them.

Next

• Hello World (Next.js) — make your first call
• Multi-tenancy — orgid enforcement in depth
• BaseModel<T> — the wrapper, in detail