# Instances

> An Instance is a workspace within an organization - the scope your product data lives in.

An **Instance** is a workspace inside an [Organization](/api/identity/organizations/) - the scope your catalog and product data live in. An organization can own several instances (for example one per brand, market or environment), each isolated from the others.

Every instance has a human-readable `name` and a stable, URL-safe `handle`. The handle is the instance's permanent identifier and doubles as the **tenant** in product service hostnames: the Product Management API for an instance with handle `acme-eu` lives at `https://acme-eu.product-management.flowkiwi.net`, scoped further to an organization through the `X-Flowkiwi-Organization-Id` header.

## The Instance object

## How organizations, instances and product data fit together

1. A partner creates an [Organization](/api/identity/organizations/create/) and becomes its owner.
2. The organization owner creates one or more **instances** - [`POST /organizations/{organizationId}/instances`](/api/identity/instances/create/).
3. Product data (products, variants, options...) is then read and written against that instance through the [Product Management API](/api/product-management/), scoped by the organization header.

## Common workflows

- **Spin up a new workspace.** [`POST /organizations/{organizationId}/instances`](/api/identity/instances/create/) with a `name` and a `handle`. The handle must be unique and is fixed for the life of the instance.
- **Rename without breaking integrations.** [`PATCH`](/api/identity/instances/rename/) changes the display `name` only; the `handle` never changes, so existing integrations keep working.
- **Hand an instance to another organization.** [`POST .../transfer`](/api/identity/instances/transfer/) moves ownership of an instance to a different organization.

## Conventions

### Authentication

All requests require an OAuth 2.0 bearer token:

```
Authorization: Bearer <token>
```

Identity is platform-scoped: there is **no** `X-Flowkiwi-Organization-Id` header. The target organization is taken from the `{organizationId}` path parameter, and ownership checks are enforced against the partner identity in your token.

### Partial updates

`PATCH` uses [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7396) with `Content-Type: application/merge-patch+json`.