The platform lifecycle — from `ibl.ai/join` to a running app

Mirrored from iblai/vibe · docs/platform-lifecycle.md. This page is generated — edit it in the repository, not here.

Read this once, before /iblai-vibe-ops-init. It is the part of the journey that happens outside your code: getting an organization, the two values every app needs, how the organization is billed, and the settings that only exist in the ibl.ai OS. Ten steps; most take a minute.

Words: organization (org) is your workspace; its org key is its id; an agent is what the API calls a mentor. Full list in glossary.md.

1. Get an organization — ibl.ai/join

Sign up at https://ibl.ai/join. It creates your account and your own organization, and leaves you signed in.

Every account also belongs to a shared organization called main. That one is everyone's, not yours: apps built with vibe refuse it, and nothing you configure there is private. If /me (step 3) shows only main, you still need to create an organization at ibl.ai/join.

2. Your organization lives in the OS — os.ibl.ai

The OS at https://os.ibl.ai/platform/\<org-key>/… is two things at once:

• the reference app every vibe app is modelled on (its source is iblai/os), and
• the admin console for your organization — users, roles, LLM keys, API tokens, billing, memory, branding — until your own app grows an admin area (/iblai-vibe-admin).

Top-right there is a User / Admin toggle. Everything below that says "Admin mode" needs it switched to Admin.

3. Value one: the org key

Open https://login.iblai.app/me. Each organization you belong to is listed with its key — a slug like acme or a UUID. The same key is the path segment after /platform/ in every OS URL.

Check it exists (public read, no auth):

curl -fsS https://api.iblai.app/dm/api/core/orgs/<org-key>/metadata/ | head -c 200
# 200 with "platform_name" → the key is right · 404 → typo

This is PLATFORM in iblai.env and NEXT_PUBLIC_MAIN_TENANT_KEY in .env.local.

4. Value two: a Platform API Token

Your app's server (deploys, admin routes, anything with no SDK component) authenticates with one org-scoped secret. Three ways to get it:

1. In the OS (no tooling): Admin mode → settings → Integrations → APIs tab → Add API. Name it after the app (my-app), leave the expiry empty, keep the default Owner permissions, Submit. The secret is shown once — copy it now. (The same key list is reachable from any agent's Edit Agent → Integrations → API; they are one store.)
2. From your agent: npx skills add iblai/vibe --all then /iblai-api-login — it reads the signed-in session and mints the token for you (needs a browser tool such as claude --chrome).
3. CI / headless: an org secret (issued for automation) works directly as the token.

Verify it, and learn your username at the same time (the deploy skill needs IBLAI_USERNAME):

curl -fsS -H "Authorization: Api-Token <token>" https://api.iblai.app/dm/api/core/token/verify/
# 200 with {"username": "..."} → keep both values · 401 → wrong token

This is TOKEN in iblai.env and IBLAI_API_KEY in .env.local. Both files are gitignored in every vibe app; never paste the token into a chat transcript, a commit, or a screenshot. It is also a standard OpenAI-style key for the platform's OpenAI-compatible endpoint (https://asgi.data.iblai.app/api/ai-mentor/orgs/<org-key>/v1, Authorization: Bearer) — server-side only.

5. How you are billed — credits

Admin mode → settings → Billing.

• Plan & Credits: your plan (Free → Trial → Premium, Upgrade goes through Stripe checkout), your credit balance, Add Credits, and Auto Recharge (opt-in: threshold, amount, optional spending limit; needs a payment method on file, added via Manage Billing → Stripe portal).
• Agents draw credits down as they run. The balance is a hard ceiling: when it is spent, agents pause. No per-seat fees.
• Spend Limits: one org-wide cap on LLM cost per day/week/month/year, Block Requests or Alert Only, alerts at 80 % / 95 %.
• Agent Limits: the same per agent, and per user on an agent.

For what to charge your users, see /iblai-vibe-pricing.

6. More models — your own LLM keys

Admin mode → settings → Integrations → LLMs → Add LLM. Pick a provider (OpenAI, Anthropic, Google, Azure OpenAI per deployment, …) and paste its key; it is stored masked. Agents in the org can then select those models (/iblai-vibe-agent-llm). Costs by provider and model appear under Analytics → Costs.

7. Agents

Create one in the OS (Explore → Create Agent, or /create-mentor), or from your app with /iblai-vibe-agent-create, or headless with /iblai-api-agent-create. An agent's id is the UUID at the end of its OS URL: https://os.ibl.ai/platform/<org-key>/<agent-uuid>. The vibe-starter /setup page lets an admin pick or create the app's default agent without touching env files.

8. People — users and admins

Admin mode → settings → Management → Users: every member with a Role (Admin / User), optional Policies (finer grants from the Roles + Policies tabs), and an active/inactive Status. Invite sends one email or a CSV (email, first_name, last_name, platform_key, company_name, user_group). The same surface is what /iblai-vibe-admin mounts inside your app.

9. Sign-in must be allowed to come back — redirect origins

SSO returns the user to your app only if the app's origin is among the organization's allowed redirect origins. http://localhost:3000, every deployed URL (https://<name>.vercel.app and any custom domain), and a mobile custom scheme (<scheme>://, see /iblai-vibe-ops-build) each need to be listed. If sign-in redirects to login.iblai.app and never returns, this is the first thing to check — ask your ibl.ai operator to add the origin.

10. Charging your users — three rails, one decision

/iblai-vibe-pricing walks through the choice.

Before you run /iblai-vibe-ops-init

• I have my own organization (not main) and its org key — the metadata curl returns 200.
• I have a Platform API Token — token/verify/ returns 200 and I noted the username.
• I know which agent the app fronts, or I will create one on /setup.
• http://localhost:3000 is an allowed redirect origin (ask if unsure).
• I have Node 20+ and pnpm (or npm), and Claude Code / Cursor with npx skills add iblai/vibe --all done.

Then: /iblai-vibe-ops-init → pnpm dev → sign in → /setup.