# Organizations, projects and service instances

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

```
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](/concepts/trust) 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**

```bash
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**

```ts
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**

```python
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](/units-code/concepts).

## Access

You authenticate with a bearer token: your login session, or an [API token](/concepts/capabilities#api-tokens) 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.