Copy page

Zaroz Cloud v2 concepts

Organizations, projects and service instances

Everything you buy or run in Zaroz Cloud v2 sits in one tree:

Code
Organization            who pays and who may do what (members, roles, API tokens, standing)
 └─ Project             a folder of related things: "Production", "Staging"
     └─ Subscription    one purchase of a product and plan; the thing that renews and bills
         └─ Service instance   the running service: a game server, a VPS, a Workload...
              └─ resources     pods, volumes, endpoints, backups...

There are no orders in v2. A purchase is a subscription; the service it runs is a service instance.

Organizations

An organization is the billing and permission boundary. Every account has a personal organization; you can create or join others. A member is an Owner, an Admin or a regular member, and the role decides who can buy (Owner or Admin), change billing and mint API tokens. Money, standing and unit limits are all per organization.

Projects

A project groups services inside an organization and is the unit you address in the console and in most API paths. slug is unique within the organization.

curl

Code
curl -sS "$ZAROZ_API/projects" -H "$AUTH"                                  # every project you can see
curl -sS -X POST "$ZAROZ_API/organizations/<org uuid>/projects" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"name": "Production", "slug": "production"}'

TypeScript

Code
import { call } from "./zaroz";

const mine = await call("GET", "/projects");
const created = await call("POST", `/organizations/${ORG}/projects`, { name: "Production", slug: "production" });
console.log(mine.body.map((p: any) => p.slug), created.body.id);

Python

Code
from zaroz import call

_, mine = call("GET", "/projects")
_, created = call("POST", f"/organizations/{ORG}/projects", {"name": "Production", "slug": "production"})
print([p["slug"] for p in mine], created["id"])

When you buy without naming a project, the purchase goes to the organization's default project, which is created on the first purchase.

Subscriptions and service instances

A subscription is one purchase: product, plan, region, size. It carries the price, the renewal date and the invoices. A service instance is the service that subscription runs. You buy one thing and get one service, so people often use the words interchangeably in the console; the API keeps them apart because they have different ids:

You want to	Address	Id of
change billing: renew, resize, cancel	/subscriptions/{id}/...	the subscription
operate the service: start, deploy, files, logs	/service-instances/{id}/...	the service instance
operate the units of a Workload	/projects/{project_id}/service-instances/{id}/units...	the project, and the service instance

A Workload is a service instance of the Workload product: your app, running as one or more units.

Access

You authenticate with a bearer token: your login session, or an API token limited to exactly what you choose. Every route checks both that you are a member of the owning organization and that your token (if it is a restricted one) holds the permission for that action on that resource. A resource you cannot see answers 404, the same as one that does not exist.