Creating a Tenant
Creating a tenant provisions everything it needs, in two stages. Its own identity realm, its first company, an Administrator role and the first admin user assigned to that role are created while you wait. Its own database, and a schema for each product you chose, follow in the background seconds later. There is no separate setup step to run afterwards: the admin can sign in as soon as the wizard finishes, and each product becomes usable as its schema lands.
Before you start
You need platform-administrator access to the admin console, and the following to hand:
- Tenant identity — The display name and a URL-safe slug.
- Sign-in methods — Whether the tenant allows local passwords, SSO, or both.
- Products — Which Beak products this tenant gets. You can change this later.
- First company — The name of the organization the tenant's users belong to.
- First admin — Name, email, and an initial password.
Create the tenant
Open Tenants and click New Tenant. The wizard has five steps.
1. Identity
| Field | Notes |
|---|---|
| Display name | The tenant's name as it appears throughout the console. |
| Slug | URL-safe identifier, derived automatically from the display name until you edit it. Used in the tenant's login URL and its identity realm, so it cannot be changed later. |
| Custom domain | Optional. The hostname the tenant's branded login page is served on. |
| Beak AI Tenant ID | Optional numeric id used by downstream Beak AI services. |
2. Authentication
Choose which sign-in methods the tenant allows:
- Local password — Users sign in with credentials held in the tenant's own identity realm.
- SSO — Users federate through an external identity provider. Selecting this also asks for the IdP redirect path.
You can select both, in which case each user is marked as local or SSO individually when they are created. This choice also determines whether the wizard asks for an admin password in step 5.
3. Products
Choose which products this tenant gets. The list shows every product registered on the platform.
Your choice decides three things:
- Which product schemas are created — one per selected product, in the tenant's database.
- What the Administrator role covers — the role created in step 4 spans exactly the products you pick.
- Which tiles the tenant's users see — a product the tenant does not have is not shown at all, as against a product their role does not grant, which appears but is not selectable.
You can change this later on the tenant's detail page. Enabling a product afterwards provisions it in the background. Disabling one removes access only — its schema and its data are kept, so re-enabling it later restores what was there.
4. Company
Every tenant needs at least one company. Companies scope a tenant's users and roles, so the tenant cannot hold users until one exists.
| Field | Notes |
|---|---|
| Company name | Required. Defaults to the tenant's display name, which is the common case for a single-company tenant. |
| Description | Optional. |
| Email domains | Optional, comma-separated. Routes a sign-in email address to this company's identity provider — a user entering someone@acme.com is matched to the company claiming acme.com. |
Alongside the company, Beak creates an Administrator role scoped to it, covering the products you selected in the Products step. The admin from the next step is assigned this role.
5. Application admin
The tenant's first admin.
| Field | Notes |
|---|---|
| First name / Last name | Required. |
| Required. This is their sign-in identity, and what Beak records as the tenant's application admin. | |
| Password | Required only when the tenant allows local sign-in. Share it securely; the admin should change it at first sign-in. Hidden for an SSO-only tenant, where the identity provider owns the credential. |
Click Create tenant. The tenant, its realm, its company and its admin are created as a single unit — if any part of that fails, nothing is created, so you can correct the input and retry. Its database and the product schemas follow in the background.
What gets created
- Tenant — With its own identity realm and sign-in client.
- Default settings — Branding, security policy, and MFA baselines you can tune afterwards.
- Its own database — Created for this tenant alone, with a schema for each product you selected.
- First company — Including its organization in the identity backend.
- Administrator role — Scoped to that company, covering the products you selected.
- Application admin — A user in the tenant, in that company, holding the Administrator role.
The identity part is created while you wait: if any of it fails, nothing is created and you can correct the input and retry. The database and the product schemas are created in the background immediately afterwards, because creating a database takes a few seconds and each product is asked separately. Watch it on the tenant's Products & Provisioning card.
Each product also puts its own defaults in place and reports what the tenant's administrator still has to configure — see What Each Product Sets Up.
Application admin vs. IAM administrator
These are two different things, and the distinction matters:
- Application admin — A user inside the tenant. They hold admin rights across the tenant's Beak products and sign in through the tenant's login page. This is who the wizard creates.
- IAM administrator — Shown as
Tenant Adminon the Users and Administrators pages. A console user who manages tenant configuration in the Beak IAM admin console itself.
The admin created by the wizard is an application admin. If that person also needs access to the IAM admin console, create them separately on the Administrators page.
Changing the application admin
Open the tenant's detail page and edit the Application Admin card. Enter the email address of an existing user in that tenant and save — admin rights follow that address the next time the user signs in.
Note: This does not create a user. The address should match someone already provisioned on the Users page. Use it only to hand the role to a different existing user.
After creating the tenant
- Add users — On the Users page, assigning each to a company and one or more roles.
- Refine roles — Adjust the Administrator role, or add narrower roles, on the Roles page.
- Brand the login page — See Login Branding & Custom Domains.
- Check what each product still needs — See What Each Product Sets Up.
- Choose how products open — New browser tab or the current one. See Product Launch Behavior.
- Add companies — If the tenant covers more than one organization.
Watching provisioning finish
The tenant's detail page has a Products & Provisioning card showing whether its database was created, whether it is registered, and how each product got on. Each product reads as one of:
| State | Meaning |
|---|---|
Provisioned | The product created its schema. |
Awaiting setup | Provisioned, but its administrator has not finished setting it up inside the product yet. |
Not deployed here | The product is not running in this environment. Not a failure — it will create its schema when it is next deployed. |
Failed | The product could not be reached or errored. The reason is shown; Run provisioning retries. |
A product failing does not hold up the others, and it does not undo the tenant: the tenant exists, its database exists, and the products that worked are usable.
Run provisioning is safe to use as often as you like. It asks each product to try again and leaves the tenant's database sign-in details exactly as they are, so retrying a single failed product cannot disturb the products that already worked.
If provisioning has not run at all, the card says so. It also reports when this environment is not set up for automatic provisioning, in which case tenant databases are created by the platform team.
Troubleshooting
| Symptom | Cause |
|---|---|
Tenant slug already exists | The slug is taken. Slugs are unique across the platform. |
| The company name is reported as already in use | Another company in this tenant already has that name. |
| The password is rejected | It does not meet the realm's password policy. The message states the reason. |
| An identity-provider error | The identity backend could not be reached. Nothing was created — retry once it is available. |
| The Administrator role shows no products | No products were selected in the Products step, or none are registered on the platform yet. Change the tenant's products on its page, or register them under Role Services first. |
Best Practices
- Keep the slug stable — It is baked into the tenant's login URL and identity realm and cannot be changed after creation. Agree it before you start.
- Use one company per organization — Add a second company only when the tenant genuinely covers separate organizations, since companies scope both users and roles.
- Set email domains up front — They drive email-to-organization sign-in routing, and adding them later means re-testing that routing.
- Treat the initial password as temporary — Share it over a secure channel and have the admin change it at first sign-in.
- Re-check the Administrator role after changing a tenant's products — It covers the products selected when the tenant was created, so enabling one later does not add it to the role by itself.
- Keep the application admin and IAM administrator roles deliberate — Grant IAM console access only to people who administer tenant configuration, not to every product admin.