# Create a Tenant

## Prepare Tenant Information

Prepare the required details for the tenant you want to create:

* **Tenant name** - A unique identifier for the tenant.
* **Administrator email** - The primary contact who will receive access credentials and manage the tenant’s environment.

Refer to the [Tenant](https://app.gitbook.com/s/LYHZWRVgpD7c9mHAx1Vk/organizations/tenant) API endpoint for more details.

## Create the Tenant

To register a new tenant in the system, send a `POST` request to the `/api/v1/tenants` endpoint with the tenant information. This creates the tenant and assigns it a unique domain under your managed wildcard DNS (e.g., `tenant-name.runai.hostorg-domain.com`) and exposes tenant-facing services.

**Example request:**

```bash
curl -L 'https://console.<DOMAIN>/api/v1/tenants' \ 
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <TOKEN>' \ 
{
  "name": "mytenant",
  "email": "administrator@mytenant.com"
}
```

After the tenant is successfully created, the API response includes a `domain` field. This is the fully qualified domain name (FQDN) that the tenant will use to access NVIDIA Run:ai services, either through a web browser or programmatic integration.

You will [share](/multi-tenant/organization-life-cycle/organization-onboarding/share-tenant-access-details.md) this domain with the tenant’s administrators once cluster provisioning and connectivity steps are complete.

**Example response:**

```bash
tenant": {
    "id": 1,
    "name": "example",
    "displayName": "Example",
    "status": "Ready",
    "tenantId": 123,
    "eulaSigningUser": {
      "email": "user@tenant",
      "date": "2020-01-01T00:00:00Z",
      "ip": "192.168.10.210"
    },
    "created_at": "2020-01-01T00:00:00Z",
    "updated_at": "2020-01-02T00:00:00Z",
    "deleted_at": null
  },
  "additionalData": {
    "tenantDomain": "mytenant.<globaldomain>",
    "testUser": {
      "tenant-test@run.ai": "Abc!23"
    },
    "customerUser": {
      "administrator@mytenant.com": "<password>"
    }
  }
}
```

## View Existing Tenants

To retrieve a list of tenants registered in the system, send a `GET` request to the `/api/v1/tenants` endpoint. This returns details for each tenant, including the name, status, and domain information. You can use this endpoint to verify whether a tenant already exists or to audit tenant states across environments.

**Example request:**

```bash
curl -L 'https://console.<DOMAIN>/api/v1/tenants' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Accept: application/json'
```

**Example response:**

```bash
[
  {
    "id": 1,
    "name": "example",
    "displayName": "Example",
    "status": "Ready",
    "tenantId": 123,
    "createdAt": "2020-01-01T00:00:00Z",
    "updatedAt": "2020-01-02T00:00:00Z",
    "deletedAt": null
  }
]
```

**Tenant status values:**

The `status` field indicates the current lifecycle state of the tenant. Possible values include:

* `Creating` - The tenant is being provisioned.
* `Updating` - The tenant is being reconfigured.
* `Ready` - The tenant is active and fully operational.
* `Deleting` - The tenant is being decommissioned.
* `Deleted` - The tenant has been removed.
* `Failed` - Tenant creation or update has failed.

Use these values to track the readiness of tenant environments or detect errors during provisioning.


---

# Agent Instructions: 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:

```
GET https://run-ai-docs.nvidia.com/multi-tenant/organization-life-cycle/organization-onboarding/create-a-tenant.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.