> Source: https://builder-docs.ema.ai/api-reference/tenant-management
> Title: Tenant Management

# Tenant Management

Tenants in Ema form a hierarchy. A root tenant sits at the top, and child tenants inherit configurations from their parent. This page covers the APIs for creating, querying, and managing tenants.

## Tenant Hierarchy

```
Root Tenant
├── Child Tenant A
│ ├── Grandchild Tenant A1
│ └── Grandchild Tenant A2
└── Child Tenant B
```

Each tenant has its own set of AI Employees, workflows, dashboards, and users. Child tenants can inherit templates and configurations from their parent.

## CreateTenant

Create a new child tenant under an existing parent tenant.

Property

Value

URL

`/tenant.v1.TenantService/CreateTenant`

HTTP Method

POST

Protocol

gRPC-Web over HTTP

### Headers

Header

Type

Required

Description

`Authorization`

string

Yes

Bearer token

`Content-Type`

string

Yes

`application/grpc-web+proto`

`x-grpc-web`

string

Yes

`1`

### Request

Field

Type

Required

Description

`tenant_name`

string

Yes

Display name for the new tenant

`parent_id`

string

Yes

UUID of the parent tenant

`admin_email`

string

Yes

Email address of the tenant admin

### Response

Field

Type

Description

`tenant_id`

string

UUID of the newly created tenant

## CreateTenantWithApiKey

Create a new child tenant and simultaneously generate an API key for it.

Property

Value

URL

`/tenant.v1.TenantService/CreateTenantWithApiKey`

HTTP Method

POST

Protocol

gRPC-Web over HTTP

### Headers

Header

Type

Required

Description

`Authorization`

string

Yes

Bearer token

`Content-Type`

string

Yes

`application/grpc-web+proto`

`x-grpc-web`

string

Yes

`1`

### Request

Field

Type

Required

Description

`tenant_name`

string

Yes

Display name for the new tenant

`parent_id`

string

Yes

UUID of the parent tenant

`admin_email`

string

Yes

Email address of the tenant admin

### Response

Field

Type

Description

`tenant_id`

string

UUID of the newly created tenant

`api_key`

string

API key for the new tenant

## GetTenant

Retrieve details about a specific tenant.

Property

Value

URL

`/tenant.v1.TenantService/GetTenant`

HTTP Method

POST

Protocol

gRPC-Web over HTTP

### Headers

Header

Type

Required

Description

`Authorization`

string

Yes

Bearer token

`Content-Type`

string

Yes

`application/grpc-web+proto`

`x-grpc-web`

string

Yes

`1`

### Request

Field

Type

Required

Description

`tenant_id`

string

Yes

UUID of the tenant

### Response

Field

Type

Description

`tenant_id`

string

UUID of the tenant

`tenant_name`

string

Display name of the tenant

`parent_id`

string

UUID of the parent tenant

`admin_email`

string

Email of the tenant admin

## GetUsers

Retrieve the list of users associated with a tenant.

Property

Value

URL

`/api/get_users`

HTTP Method

GET

Protocol

REST (HTTP/JSON)

### Headers

Header

Type

Required

Description

`Authorization`

string

Yes

Bearer token

### Response

Returns a list of user objects associated with the authenticated tenant.

Field

Type

Description

`users`

array

List of user objects

`users[].id`

string

UUID of the user

`users[].email`

string

Email address of the user

`users[].role`

string

Role of the user in the tenant

## Related

-   [Getting Started](/legacy-docs/api-reference/getting-started) -- Quickstart guide
-   [Authentication](/legacy-docs/api-reference/authentication) -- API key and token management