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 |
| 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 | Tenant | Yes | Tenant definition: domain, company_name, email; optional size, parent_tenant_id, alternate_domains. Parent is inferred from the caller's token if parent_tenant_id is omitted. |
user_name | string | Yes | Name of the initial tenant admin user |
user_email | string | Yes | Email of the initial tenant admin user |
user_create_api_key | boolean | No | If true, returns API keys for the admin in the response |
additional_users | array | No | Extra users to seed alongside the admin |
workspace_name | string | No | Default workspace name |
size | integer | No | Expected tenant size |
third_party_direct_login_config | object | No | SSO/IDP configuration for direct login |
Response
| Field | Type | Description |
|---|
tenant | Tenant | The created Tenant (id, domain, company_name, email, default_workspace_id, parent_tenant_id, size, alternate_domains) |
api_keys | array | API keys generated for any seeded users with create_api_key set |
CreateTenantWithApiKey
Create a new child tenant and simultaneously generate API keys for its admin users. Unlike the other endpoints in this section, this is a REST endpoint (not gRPC-Web) — it wraps CreateTenant but exposes a flatter request/response shape that some integrations target directly.
| Property | Value |
|---|
| URL | /api/tenant/create_tenant_with_api_key |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Request
| Field | Type | Required | Description |
|---|
domain | string | Yes | Tenant domain (subdomain slug) |
company_name | string | Yes | Display name for the tenant |
email | string | Yes | Contact email for the tenant |
admin_users | array | Yes | One or more admin user definitions: { user_name, email, create_api_key }. The first entry becomes the primary admin; the rest are added as additional users. |
alternate_domains | array | No | Additional domains the tenant should also be reachable at |
size | enum | No | Expected tenant size (TenantSize enum value) |
login_redirect_url | string | Conditional | Required only when third-party direct login is enabled for this Ema instance |
logout_redirect_url | string | Conditional | Required only when third-party direct login is enabled for this Ema instance |
Response
| Field | Type | Description |
|---|
tenant_id | string | UUID of the newly created tenant |
api_keys | array | Per-admin API keys, each { email, api_key }. Populated for each admin user that had create_api_key=true. |
GetTenant
Retrieve details about the tenant associated with the caller's token.
| Property | Value |
|---|
| URL | /tenant.v1.TenantService/GetTenant |
| HTTP Method | POST |
| Protocol | gRPC-Web over HTTP |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/grpc-web+proto |
x-grpc-web | string | Yes | 1 |
Request
Empty request body — the tenant is resolved from the caller's access token.
Response
| Field | Type | Description |
|---|
tenant | Tenant | Tenant details: id, domain, company_name, email, default_workspace_id, alternate_domains, parent_tenant_id, size |
GetUsers
Retrieve the list of users associated with a tenant.
| Property | Value |
|---|
| URL | /api/user/get_users |
| HTTP Method | GET |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Response
Returns a list of user objects associated with the authenticated tenant.
| Field | Type | Description |
|---|
total | integer | Total number of users in the tenant |
users | array | List of user objects |
users[].id | string | UUID of the user |
users[].name | string | Display name of the user |
users[].email | string | Email address of the user |
users[].is_admin | boolean | Whether the user is a tenant admin |
users[].tenant_id | string | UUID of the tenant the user belongs to |
users[].status | string | Current user status (e.g. active, invited) |