Create your organization and instance

Before you can manage products, you need two things in Identity: an organization (your top-level account) and an instance inside it (the workspace your catalog lives in). This guide creates both.

Before you start

You need an OAuth 2.0 bearer token for a partner account. Sign in below and your token is dropped into every command on this page (each request sends it as Authorization: Bearer {token}). See Authentication for more.

Sign in to drop your real token into the commands below.

Identity is platform-scoped: you call it on https://identity.flowkiwi.net, with no organization header - you don’t have an organization yet.

Follow the IDs

Each step returns an identifier you reuse later: the organization id (step 1) and the instance handle (step 2). Copy them as you go.

Steps

1. Create an organization

   The organization is your top-level account. The authenticated partner becomes its first owner, so this is the one call that takes no organization context.

   curl -X POST 'https://identity.flowkiwi.net/api/organizations' \
     -H 'Authorization: Bearer {token}' \
     -H 'Content-Type: application/json' \
     -d '{ "name": "Acme Corp" }'

   The response carries the new organization id - keep it:

   {
     "id": "0196f3a0-1111-7000-8000-000000000001",
     "name": "Acme Corp",
     "owners": [
       { "id": "0196f3a0-2222-7000-8000-000000000001", "email": "jane@acme.example", "role": "owner" }
     ],
     "members": []
   }

   See the Create an organization reference for all fields.

2. Create an instance

   An instance is a workspace inside the organization - the scope your catalog lives in. Give it a display name and a unique, URL-safe handle. Use the organization id from step 1 in the path.

   curl -X POST 'https://identity.flowkiwi.net/api/organizations/0196f3a0-1111-7000-8000-000000000001/instances' \
     -H 'Authorization: Bearer {token}' \
     -H 'Content-Type: application/json' \
     -d '{ "name": "Acme EU", "handle": "acme-eu" }'

   {
     "id": "0196f3a0-3333-7000-8000-000000000001",
     "handle": "acme-eu",
     "name": "Acme EU",
     "organization_id": "0196f3a0-1111-7000-8000-000000000001"
   }

   The handle is your tenant

   The handle doubles as the tenant in product service hostnames and is permanent. With handle: "acme-eu", your Product Management API lives at https://acme-eu.product-management.flowkiwi.net. Pick it carefully - only the display name can change later.

What you built

Organization "Acme Corp"
└─ Instance "Acme EU"  (handle: acme-eu → acme-eu.product-management.flowkiwi.net)

Next step

With your organization and instance ready, create your first product on the instance.