Build an App
A marketplace app is a product of its own, built on Perfox, that a workspace turns on from the App Marketplace. The first one is the CRM. This page is for the team building one: what an app is, how it is put together, how it connects to Perfox, and the steps from an empty repo to an app people open from their workspace.
Start with the app developer skill
In Studio, open Developer → Build an app and press Download the skill. You get a zip with a guide and 11 references that teach Claude Code the whole contract on this page. Unzip it into ~/.claude/skills/ (or your app repo's .claude/skills/) and ask Claude in plain words, for example "add the create handler".
What an app is
An app has its own code base, its own data and its own web address, and one deployment serves all the workspaces that turn it on. Perfox is the agent platform; your app is the system of record and the place your users work.
It meets Perfox in exactly five ways, and no other:
| # | Direction | What crosses | What it's for |
|---|---|---|---|
| 1 | Perfox → your app | The tenant API | Perfox creates, reads, suspends, resumes and cancels your app's copy for a workspace |
| 2 | A person → your app | The launch token | Open in Perfox signs the person in, with a 60-second single-use token. Your app has no passwords and no sign-up |
| 3 | Your app → Perfox | The public API | Your app calls /api/v1 with the one key Perfox issues it for that workspace |
| 4 | Perfox agents → your app | Your MCP server | Perfox registers it in the workspace, and agents use your app's tools through it |
| 5 | Your app → Perfox | The manifest | Your app lists the agents it needs, and Perfox installs them in the workspace |
Your app never imports Perfox code, never reads Perfox's database, and never calls Perfox's internal routes.
How an app is structured
<workspace> is the workspace's slug and <app> is your app's slug.
| Address | What lives there |
|---|---|
https://<workspace>.<app>.perfox.ai | Your app for that workspace, with /auth/launch where people arrive signed in |
https://<workspace>.<app>.perfox.ai/mcp | Your MCP server for that workspace |
https://admin.<app>.perfox.ai | Your console and your tenant API (/api/platform/v1). The tenant API answers only here |
https://<workspace>-api.perfox.ai | The workspace's Perfox API. Perfox sends it to you when the workspace turns your app on; never build it yourself |
The tenant API your app serves, and when Perfox calls it:
| Call | When |
|---|---|
POST /tenants | A workspace turns your app on, a retry, or a re-enable |
GET /tenants/{id} | Perfox reads your copy's state |
POST /tenants/{id}/suspend | A renewal wasn't paid, or the workspace was suspended |
POST /tenants/{id}/resume | A renewal went through, or the workspace is back |
POST /tenants/{id}/cancel | The app was cancelled |
POST /tenants/{id}/users/{user_id}/revoke | A person lost access in Perfox |
POST /tenants/{id}/mcp-key | Perfox needs the key it registers your MCP server with |
POST /tenants/{id}/database | Perfox hands over the workspace's app database, or a new address for it |
GET /manifest | Perfox reviews or pins the agents your app needs |
Each call waits at most 10 seconds, and a call your app doesn't take is sent again. So every call must be idempotent on the workspace's Perfox tenant id, and every refusal carries { code, message }. Perfox shows your message to the people concerned.
How it connects to Perfox
Sign-in. The launch token arrives in the URL fragment at /auth/launch. It is a JWT signed with the workspace's key, carrying:
- the person:
sub,email,name; - the claims you check:
aud(your slug),tenant_id,jti, andexp(60 seconds after it was issued); - an
app_role(adminoroperator); - a relative
return_topath.
Your backend checks, in this order:
- the signature, against
<workspace API>/api/auth/jwks; aud;exp;- that this
jtiwas never used before; - that
tenant_idis the workspace your address resolves to.
Your key. Perfox issues one sk_ key for each workspace that turns your app on, and sends it at create.
- Scopes: fixed by your app's listing. The CRM's include conversations, customers, agents, files and webhooks.
- Who controls it: Perfox. A workspace admin can't rotate it, widen it or delete it.
- When it ends: it is revoked when your app is cancelled.
Files. Your app keeps no storage of its own: upload through App Files.
Webhooks. Your app's key may subscribe only at your app's own address for that workspace. It sees only its own subscriptions, and they are deleted when your app is cancelled.
Database. A workspace's apps share one app database, which Perfox creates and sends at create as database { name, uri }. Keep to your own collections, and never name, create or drop the database yourself.
The agents your app needs
Serve GET /api/platform/v1/manifest with a version and your agents. An agent reaches your app's own tools through an MCP node whose server is @app.
- Install: Perfox pins one version of your manifest, then installs its agents in each workspace that turns your app on, within the hour. Agents that pass Perfox's publish checks are published.
- New version: an agent nobody edited is updated. An agent the workspace edited is never overwritten.
- Dropped agent: one you remove from the manifest is left in place, no longer managed.
Your app's lifecycle
Perfox alone decides your app's lifecycle; your app carries out its calls.
| What happens | What Perfox calls | What your app does |
|---|---|---|
| A workspace turns your app on | create, then the MCP key | Make the workspace's copy |
| A renewal isn't paid | suspend, as lapsed | Stay open under a renew banner; notices follow at 30, 60 and 90 days |
| The renewal is paid | resume | Open again as before |
| The workspace is suspended | suspend | Suspend the workspace's copy |
| The app is cancelled (at the end of the paid period, or at once) | cancel | Keep the data whole for 30 days; a re-enable inside that window restores everything |
People can open your app while it is active, lapsed or cancelling.
Build and bring an app live
- Download the app developer skill from Developer → Build an app and install it for Claude Code.
- Perfox adds your app's slug, the scopes its key needs, and its listing.
- Build the tenant API,
/auth/launch, your MCP server, your manifest and your Perfox client. - Deploy your app.
- Perfox saves and tests your app-level key, sets your plans, pins your manifest and publishes your app on the App Marketplace.
- On a test workspace: turn the app on, open it, use it, cancel it, and turn it on again within 30 days to check everything comes back.
Related
- App Marketplace: turning an app on, billing, access and cancelling, from the workspace side
- App Files: file storage for your app
- API Keys and the Developer Hub