Tenants

The Tenants screen lets you list the isolated organizations of the platform, create a tenant with its first administrators and rename it. Portal path: /admin/tenants. It is used by the platform administrators (platform_admin) when they onboard an organization, and by a tenant administrator (tenant_admin) to rename their own tenant.

What the screen shows

A table Tenants with a refresh button (Refresh) and the New tenant button.

Column	Content
Slug	Short unique identifier of the tenant (lowercase letters, digits, hyphens).
Name	Display name.
Data residency	Region where the data of the tenant stays (eu by default).
Status	active or suspended.
Created	Creation date.

The list is paged by slug: the pagination under the table loads the next page of the API on demand. A click on a line opens a side panel with the full record read from the API. Empty state: No tenant yet, "Create the first tenant to onboard an organization."

Actions

Button or action	What it does	API call	Roles
Opening the screen, Refresh, next page of the pagination	Reads the tenants page by page.	GET /v1/tenants	Signed-in user; the server returns the tenants the caller may see.
New tenant then Create	Form Slug (required, for example acme), Name (required), Data residency (suggestions eu, fr, de, ch, uk, us, ca, ae, sa, sg), Admins (list of subjects, suggested from the members). Each admin receives the tenant_admin role in the new tenant.	POST /v1/tenants (suggestions: GET /v1/members)	platform_admin
Click on a line	Opens the detail panel.	GET /v1/tenants/{id}	platform_admin, or a member of that tenant
Rename	Dialog with Name (required), then Rename.	PATCH /v1/tenants/{id}	tenant_admin of the tenant, platform_admin

The status of a tenant is not changed from this screen; on the API, only platform_admin may set it.

Roles

From services/control-plane/src/eai/domains/tenancy/__init__.py:

• POST /v1/tenants requires platform_admin (require_role("platform_admin")).
• PATCH /v1/tenants/{id} requires tenant_admin; platform_admin always passes. A tenant administrator only reaches their own tenant: another tenant answers not_found. Changing the status field needs platform_admin.
• GET /v1/tenants/{id} answers for the caller's own tenant, or for any tenant to platform_admin.

The portal shows the New tenant button to every user (the configuration declares no role); the server refuses the creation with forbidden to anyone but platform_admin.

Typical tasks

Onboard a new organization

1. Open the screen. Portal: Administration > Tenants. Expected result: the table of tenants. If it fails: an error means the API is unreachable or your session expired; sign in again.
2. Create the tenant. Button New tenant: type the Slug (acme), the Name, choose the Data residency and add the subjects of the first administrators in Admins, then Create. The admins can then manage their tenant without a platform administrator. Expected result: the toast Created and a new line. If it fails: forbidden (HTTP 403) when you are not platform_admin; conflict (HTTP 409) when the slug exists.
3. Check the record. Click the new line. Expected result: the detail panel with the slug, the residency and the status active. If it fails: not_found means the tenant is outside your scope.

Rename a tenant

1. Open the action. Row menu > Rename. Expected result: a dialog with the current name. If it fails: no menu means the list did not load; click Refresh.
2. Type the new name and confirm. Button Rename. Expected result: the toast Done and the new name in the table. If it fails: forbidden when you are neither tenant_admin nor platform_admin; not_found for a tenant that is not yours.

Troubleshooting

Symptom	Cause	Fix
forbidden (HTTP 403) on Create	Only platform_admin creates a tenant.	Ask a platform administrator.
conflict (HTTP 409) on Create	The slug is already used by another tenant.	Choose another slug.
Validation error on Slug	The slug does not match the expected pattern (lowercase letters, digits, hyphens).	Type a slug such as acme or acme-eu.
not_found (HTTP 404) on the detail or Rename	The tenant is not yours and you are not platform_admin, or the identifier is not a UUID.	Work on your own tenant or sign in as platform_admin.
An admin cannot manage the new tenant	The subject typed in Admins is not the one of the identity provider.	Add the right subject in Members and roles.

Related pages

• Projects and environments
• Organizations and business units
• Members and roles
• Licence and support
• Getting started