Product scaffold

A working starter (Go 1.22 + Gin) that plugs into bizbasics. It implements the full SSO contract (/auth/sso, /bootstrap, /health, /ready), publishes a workspace record from its backend, and reports usage to the platform. Copy it, rename, and you have the integration done — focus on your product.

1. Get the scaffold

cp -r product-scaffold my-product   # from the bizbasics product template
cd my-product
# rename the placeholders to your product slug + port:
grep -rl PRODUCT_NAME . | xargs sed -i '' 's/PRODUCT_NAME/my-product/g'
grep -rl PRODUCT_PORT . | xargs sed -i '' 's/PRODUCT_PORT/8200/g'

2. Configure

Get your product's SSO secret from Settings → SSO credentials (it authenticates your token exchange) and a write-scoped API key from Settings → API keys. Then fill .env:

cp .env.example .env

AUTH_SERVICE_URL=https://auth.bizbasics.ai
PLATFORM_API_URL=https://api.bizbasics.ai
BIZBASICS_APP_SSO_SECRET=...     # your product SSO secret (sent as X-Internal-Key)
APP_SESSION_SECRET=...           # random 32+ bytes; signs your own session cookie
DATABASE_URL=postgres://...      # your product's own DB
COOKIE_DOMAIN=my-product.example.com

3. Run

docker compose up      # boots the service + runs its migrations
open http://localhost:8200

Unauthenticated traffic is redirected through the platform; after the SSO handshake your product renders with the user's identity from /bootstrap.

4. Publish workspace records

When your product creates a user-visible object, publish a summary from your backend so it surfaces across the suite:

POST {PLATFORM_API_URL}/v1/workspace-records
  Authorization: Bearer bbk_...
  {
    "org_id": "{org_id}", "source_product": "my-product",
    "record_type": "deal", "source_ref": "{deal.id}",
    "title": "{deal.title}", "app_href": "/deals/{deal.id}"
  }

The scaffold wraps this in workspace_publisher.go. See the API reference for the full field list.

5. Submit for review

When you're ready for customers, submit your product for catalog listing — see Submit your app. Once approved, a platform admin provisions infra and flips it live.

Testing

Ask a platform admin to spin you up a sandbox org (throwaway, bypasses plan/seat limits, auto-cleaned after 14 days) and to grant your product to it. You can then run the whole SSO + records flow end-to-end without touching a paying customer.