Two consumption patterns

Cobuntu supports two architectures side by side. The choice isn't about which framework you use — Lovable, Next.js, Webflow, Astro, plain HTML, all of those work in either pattern. The choice is about where your apex DNS points and how auth flows.

In short:

The rest of this page goes deep on each.

Headless API

You own everything: your apex, your hosting, your runtime, your auth boundaries. Cobuntu is purely a REST backend you call from your server.

┌──────────┐ 1                  ┌────────────────────┐
│ Visitor  │ ─────────────────▶ │ yourdomain.com     │
│ browser  │                    │ (your Next.js app, │
└──────────┘ ◀───────────────── │  your Vercel)      │
                4 (HTML)        └─────────┬──────────┘
                                          │ 2 server-side fetch
                                          │   X-API-Key: sk_live_…
                                          ▼
                                ┌────────────────────┐
                                │ api.cobuntu.com    │
                                │ (Cobuntu backend)  │
                                └─────────┬──────────┘
                                          │ 3 JSON
                                          └─▶ back to your app

Use this when:

• You have an engineering team and existing brand patterns to enforce.
• You want full control over rendering: ISR, edge functions, custom caching, SEO with your existing tooling.
• You have surfaces beyond what Cobuntu provides — a custom dashboard, a B2B portal, integrations with non-Cobuntu data sources rendered alongside Cobuntu data.
• Your community already lives behind a custom-route auth/IAM system you don't want to surrender (e.g. Auth0, Clerk, NextAuth) — Cobuntu just provides the community data.
• You want to ship features Cobuntu's UI doesn't have yet, on your timeline. Build everything Cobuntu's React app provides, plus more, your way.

What you own:

• Hosting (Vercel / Netlify / Cloudflare Pages / your own server).
• DNS for yourdomain.com (apex + subdomains).
• The visitor's session — log them in via your own flow, store sessions however you like.
• All routes: /, /about, /pricing, /events, /checkout, every page. Cobuntu doesn't serve any URL on your domain.
• TLS certificates.

What Cobuntu provides:

• The REST API at api.cobuntu.com/api/v1/* — events, members, articles, products, segments, atlas, broadcasts.
• Webhooks for lifecycle events (member.approved, product.purchased, etc.).
• A publishable key (pk_live_…) for any browser-side calls you need (Cobuntu auto-provisions one per community at GET /api/communities/{tag}/publishable-key).
• A secret key (sk_live_…) for server-side calls — you generate it in cobuntu-admin → Integrations → API Keys.

Trade-offs:

• You re-implement everything Cobuntu's hosted apex provides for free: event detail pages, marketplace, cart, checkout, member directory, atlas, feed, chat, profile pages. That's months of UI work if you want feature parity.
• Visitors logging in have to go through your auth, not Cobuntu's. If you want SSO with Cobuntu (so members log in once and access both your custom routes AND Cobuntu's pages), that's /v2 work — not shipping today.
• You're on the hook for performance, uptime, accessibility, mobile.

Live in production: Orbis (opens in a new tab) and DDDIMO (opens in a new tab) — both Next.js apps hitting api.cobuntu.com/api/v1/* with X-API-Key server-side.

How to start:

1. Generate a secret key in cobuntu-admin → Integrations → API Keys.
2. Store it as a server-only env var.
3. Call https://api.cobuntu.com/api/v1/communities/{your-tag}/events etc. from your server. See REST API for the full endpoint reference.
4. (Optional) Subscribe a webhook URL for the events you care about. See Webhooks.

Hosted apex

You point your apex DNS at Cobuntu's Vercel project. Cobuntu then serves two kinds of URLs at yourdomain.com, on the same origin:

1. Your landing — reverse-proxied from wherever you host it (Lovable, Squarespace, your own Next.js, anywhere). Cobuntu fetches the HTML from your origin and re-serves it as if it were yours.
2. Cobuntu's product surfaces — /events, /marketplace, /feed, /atlas, /members, /profile, /conversations, /cart, /checkout. These render Cobuntu's React app with your branding (logo, colors, fonts pulled from cobuntu-admin → Customize).

Because both are on the same origin, they share cookies. A visitor who logs in via Cobuntu's /login (served at yourdomain.com/login) gets a cobuntu_auth cookie on yourdomain.com. The same cookie is then visible to your landing when its JS makes relative fetches.

┌──────────┐ 1                  ┌────────────────────┐
│ Visitor  │ ─────────────────▶ │ yourdomain.com     │
│ browser  │                    │ (DNS → Cobuntu's   │
└──────────┘                    │  Vercel proxy)     │
                                └─────────┬──────────┘
                                          │ 2 proxy decides:
                                          │   /         → fetch your landing
                                          │   /events   → render Cobuntu page
                                          │   /api/*    → forward to backend
                                          ▼
        ┌─────────────────────┬─────────────────────┐
        │ Your landing host   │ Cobuntu app + API   │
        │ (Lovable / SQSP /   │ (community-app +    │
        │  Webflow / Next.js) │  api.cobuntu.com)   │
        └─────────────────────┴─────────────────────┘

Use this when:

• You don't have an engineering team (or you want them focused on something other than re-implementing event-detail pages, carts, checkout flows, member directories — features Cobuntu already ships).
• You want your landing in a no-code tool (Lovable, Squarespace, Webflow, Framer) AND members to log in, browse events, buy products, chat — all under your brand at yourdomain.com, without you wiring auth or session storage.
• You want shared cart + auth across landing + Cobuntu pages automatically. Visitor adds a product on /marketplace, opens /, the cart count badge already shows it.
• You're shipping a community-first business model where Cobuntu's surfaces (events, marketplace, atlas, chat) ARE the product, and the landing is a marketing wrapper.

What you own:

• Your landing's design and HTML (in whatever tool you like).
• DNS: a CNAME from your apex pointing at Cobuntu's Vercel.
• Cobuntu branding config (logo, colors, fonts) inside cobuntu-admin.

What Cobuntu provides:

• Reverse-proxy hosting at your apex.
• All product surfaces (events, marketplace, cart, checkout, atlas, members, feed, chat, profile) — rendered with your branding.
• Auth flow: /login, /signup, session cookies, password reset, OAuth providers.
• TLS certificate via Vercel's automated provisioning.
• The data API + widgets — your landing can drop in <div data-cobuntu-cart>, <div data-cobuntu-auth>, etc. for chrome shared with the Cobuntu pages.
• Webhook delivery from lifecycle events same as Headless API.

Trade-offs:

• Less control over the product surfaces. Cobuntu owns the event detail page UX, the marketplace layout, the checkout flow. You can theme them but not redesign them.
• Routing collisions: you can't have a /events route in your landing — Cobuntu serves /events from its own pages. The reverse proxy keeps a list of "Cobuntu-owned" path prefixes (/events, /marketplace, /feed, /atlas, /members, /cart, /checkout, /profile, /login, etc.); your landing owns everything else.
• You're trusting Cobuntu's uptime + page-render quality for product surfaces.

Live in production: Bela Escala (opens in a new tab) — landing built in Lovable (bela-escala-hub.lovable.app), apex belaescala.com reverse-proxied through Cobuntu. Visitors browse /, /networking, /eventos (Lovable-served) seamlessly with /events/networking-online, /marketplace, /members (Cobuntu-served).

How to start:

1. Pick where you host your landing (Lovable / Squarespace / Webflow / your own Next.js on Vercel — anything).
2. Configure Cobuntu's reverse proxy with your landing's upstream URL — cobuntu-admin → Customize → Landing source.
3. Point your apex DNS (CNAME) at Cobuntu's Vercel target.
4. (Optional) Drop the chrome widgets into your landing — <script src="/widgets/v1/auth.js"> + <div data-cobuntu-auth> for shared header auth, same for cart/messages/notifications. See Widgets.
5. (Optional) Subscribe webhooks for automations. See Webhooks.

Common confusion: "Isn't Lovable just a Next.js app?"

Yes — Lovable is a React framework with hosting. Functionally, nothing stops a Lovable-built landing from running in either pattern. Same for a hand-written Next.js app; same for a Webflow export; same for plain HTML.

The framework doesn't pick the pattern. What picks it:

• Where your apex DNS points (your own host vs. Cobuntu's Vercel).
• Whether you want to write server code that calls our REST API, or you want our app rendered alongside your landing on the same domain.

A team running Next.js can absolutely use Hosted apex — they'd build their landing in Next.js, deploy it somewhere, and point Cobuntu's reverse proxy at it. The trade-off would be: they wouldn't get to use Next.js's server-side rendering for the landing's data (because the data fetch becomes a Cobuntu-side fetch from their origin, not a build-time call). For purely static + client-fetched landings, that's fine. For dynamic SSR, Headless API is the better fit.

Can you mix them?

Yes, at a subdomain boundary.

A common shape:

• yourdomain.com → Hosted apex (Cobuntu-managed product surfaces + your landing reverse-proxied)
• app.yourdomain.com → Headless API (your own custom Next.js dashboard hitting api.cobuntu.com/api/v1/*)

Each has its own DNS target; each plays one pattern. They don't share cookies across subdomains by default, but you can configure cookie domain widening (see the auth-widget docs).