> For the complete documentation index, see [llms.txt](https://docs.nerovasystems.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nerovasystems.com/guides/zero-to-live/step-4-provision-tenant.md).

# Step 4: Provision a tenant

**Step 4 of 10.** Create a tenant with your Live key. One tenant represents one merchant operated by the digital employee. Tenants you create while the free testing allowance lasts are real tenants; use them as your test merchants.

## 4.1 Create the tenant

`POST /api/v1/tenants` is idempotent: the `Idempotency-Key` header makes retries safe. Send your own stable identifier for the merchant as `externalReference` so you can always correlate Nerova tenants with rows in your own database.

```bash
curl -X POST https://api.nerovasystems.com/api/v1/tenants \
  -H "Authorization: Bearer $NEROVA_API_KEY" \
  -H "Idempotency-Key: 4b0a4c9e-9d43-4d4e-8f4e-6d2b3a1c5e77" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Walkthrough Salon",
    "externalReference": "merchant-42"
  }'
```

```json
{
  "id": "1539251826400956416",
  "displayName": "Walkthrough Salon",
  "externalReference": "merchant-42",
  "provisioningState": "Ready",
  "lifecycleState": "Active",
  "pendingStep": null,
  "lastErrorCode": null,
  "version": 2
}
```

Requires the `merchant:provision` scope on your key.

## 4.2 Wait for Ready

Treat `provisioningState` as asynchronous: poll `GET /api/v1/tenants` with your Live key until the tenant reports `Ready` before you continue. Do not assume synchronous completion.

```bash
curl https://api.nerovasystems.com/api/v1/tenants \
  -H "Authorization: Bearer $NEROVA_API_KEY"
```

The list returns exactly the tenants your key has been granted, as a plain array; there is no implicit organization wide access. Each entry carries the same fields as the create response: `id`, `displayName`, `externalReference`, `provisioningState`, `lifecycleState`, `pendingStep`, `lastErrorCode`, and `version`.

## 4.3 Replays and failures

* Retrying the create with the **same** `Idempotency-Key` returns the identical tenant, byte for byte. Nothing is duplicated.
* Sending a **new** `Idempotency-Key` with the same `externalReference` is rejected with HTTP 409 Conflict: `externalReference` is unique per organization and identifies exactly one tenant. Keep both the idempotency key and the reference stable per merchant in your own automation.
* A tenant that reports a failed provisioning state can be retried with a fresh create; nothing partial remains visible.

## 4.4 Test merchants

There is no fixture merchant. Create one tenant per test merchant (for example `walkthrough-salon`) and keep its `externalReference` stable. Later steps continue against the tenant you create here.

## The version counter

Notice the `version` field in the create response. Every tenant carries an optimistic concurrency version that increments on every state change. From step 7 onward, every mutating activation request must include the current version as `expectedVersion`; a stale value is rejected. Track it from the start.

## Where you are now

A tenant exists and is Ready. It has no connection to any booking platform yet, so it can do nothing. Wiring it to your Provider API implementation is next.

Continue to [Step 5: Connect your platform](/guides/zero-to-live/step-5-connect-platform.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nerovasystems.com/guides/zero-to-live/step-4-provision-tenant.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.