Multi-tenant & integrations

InstaCloud supports multi-tenancy out of the box: to make each of your customers an app or a project with exactly the right permissions, use the endpoints below. The API is directly available on any account; when you put a real fleet on it, contact us for an Enterprise plan with custom restrictions.

1. Provision the master token

Your backend keeps one master token: an organization-scoped API token, minted once (insta tokens create master --org <orgId>). It acts as your backend’s master key: it is the credential that creates projects and mints narrower tokens, never wider than itself, and it never leaves your backend. From there, give each customer the isolation boundary that matches how much they touch. In doubt, take a project per customer.

2. A project per customer

Every customer, whether that is a user of your builder or a tenant of your SaaS, gets a separate project, for token isolation. This is the shape to pick when customers freely create apps and use resources, or when each customer’s app carries its own database: mint a project-level token per customer, and everything that runs for them runs under it, inside their own project.

API=https://api.instacloud.com

# 1. A project for the new customer. Master token only.
PROJECT=$(curl -s -X POST $API/orgs/$ORG/projects \
  -H "Authorization: Bearer $MASTER" -H "Content-Type: application/json" \
  -d '{"name":"acme"}' | jq -r .project.id)

# 2. A token bound to that project alone. The plaintext is returned once;
#    store it with the customer record.
TOKEN=$(curl -s -X POST $API/tokens \
  -H "Authorization: Bearer $MASTER" -H "Content-Type: application/json" \
  -d "{\"name\":\"acme\",\"orgId\":\"$ORG\",\"projectId\":\"$PROJECT\"}" | jq -r .token)

# 3. Everything for this customer now runs under $TOKEN.
curl -s -X POST $API/projects/$PROJECT/services -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type":"postgres","name":"db"}'
curl -s -X POST $API/projects/$PROJECT/services -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type":"compute","name":"app","port":3000}'

# 4. Wire the database in, then deploy.
curl -s -X PUT $API/projects/$PROJECT/secret-bindings/DATABASE_URL \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"target":"compute/app","source":"postgres/db"}'
curl -s -X POST $API/projects/$PROJECT/deploy -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image":"ghcr.io/you/tenant-app:1.0.0","group":"app","port":3000}'

The responses are plain JSON. Creating the project answers with the project row and its default branch; minting the token answers once with the plaintext:

POST /orgs/{orgId}/projects (201)

{"project":{"id":"36b7fe0a-87a1-4db4-8fc5-9b2188962afe","org_id":"86e77ca0-...","name":"acme","status":"active","agent_policy":{"mode":"full_access"},"created_at":"2026-09-29T03:28:24.245Z"},"defaultBranch":{"id":"0ba7ab98-...","name":"main"},"resources":[]}

POST /tokens (201)

{"token":"insta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","record":{"id":"nbvAiBn5...","name":"acme","scope":"project","orgId":"86e77ca0-...","projectId":"36b7fe0a-...","access":"full","expiresAt":null,"createdAt":"2026-09-29T03:28:24.873Z"}}

The project token is the isolation boundary, so hand it to the customer’s runtime without worry:

It reaches its own project only. Any endpoint outside the binding answers 403 token_scope, and it cannot mint tokens at all.
A second token with "access":"read_only" serves customer-facing dashboards: it is accepted on GET and HEAD only.
Each customer gets their own branches for previews and agent runs (branch per task).
GET /projects/{projectId}/usage is that customer’s bill; /usage/daily gives the day-by-day series.
Offboarding is two calls with the master token: DELETE /projects/{projectId} and DELETE /tokens/{tokenId}.

Idle customers stay cheap: a project’s Postgres suspends by default and bills only for storage, and its compute can scale to zero the same way.

3. An app per customer

If all a customer interacts with is a single unit of resources, one app, say one generated app per user without a database of its own, you can skip the per-customer project: keep one shared project and make every customer a compute service of their own.

# Per customer: one app in the shared project, wired to the shared database, deployed.
curl -s -X POST $API/projects/$PROJECT/services -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"type":"compute","name":"acme","port":3000}'
curl -s -X PUT $API/projects/$PROJECT/secret-bindings/DATABASE_URL \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"target":"compute/acme","source":"postgres/db"}'
curl -s -X POST $API/projects/$PROJECT/deploy -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image":"ghcr.io/you/tenant-app:1.0.0","group":"acme","port":3000}'

Each app deploys, scales, restarts and stops on its own, without touching the rest of the fleet.
Logs and metrics still read per app: GET /projects/{projectId}/logs?group=<app>, and the same group filter on /metrics.
A database per customer inside the shared Postgres keeps separation clean: POST /projects/{projectId}/database/databases.
Usage is reported for the whole project, so per-customer billing needs your own accounting on top, and a growing fleet hits the plan’s per-branch service caps first. When a customer outgrows the shared project, promote them to a project of their own.

Either way, the organization’s audit stream (GET /orgs/{orgId}/events/stream) gives you one timeline of everything every customer’s infrastructure did.

Enterprise plans

Standard plans cap how many services of each type a branch can hold, sized for one team rather than a fleet of tenants, so an app per customer hits the compute cap first and a project per customer eventually meets its own ceilings. For production multi-tenant use, contact us to be upgraded to an Enterprise plan with custom restrictions: limits sized to your tenant count, and guardrails where you want them, per project. Tell us what you are building and roughly how many tenants you expect:

Email founders@insforge.dev, or
use the contact form.

We answer within one business day.

The API design

The full API design is published, split by which token scope can call each endpoint:

API overview: authentication, token scopes, errors, and the end-to-end provisioning flow.
Account, organization and project endpoint pages, generated from the platform’s own OpenAPI document.
GET https://api.instacloud.com/openapi.json: the machine-readable spec, if you would rather generate a client.

Overview

Database

Storage

Compute

Migrate

Agent-native

Self-hosting

Limitations

Multi-tenant & integrations

1. Provision the master token

2. A project per customer

3. An app per customer

Enterprise plans

The API design

​1. Provision the master token

​2. A project per customer

​3. An app per customer

​Enterprise plans

​The API design

1. Provision the master token

2. A project per customer

3. An app per customer

Enterprise plans

The API design