website/docs: edited Docs about tenants (#8549)

* add info

* more usage deets

* add steps

* polish procedurals

* comma tweak

* Update website/docs/advanced/tenancy.md

Co-authored-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* marc's edits

* comma tweak

* kens edits

* typo

---------

Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>
Co-authored-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

website/docs/advanced/tenancy.md

@@ -11,37 +11,67 @@ This feature is in alpha. Use at your own risk.
 ::::
 
 ::::info
-This feature is available from 2024.2 and is not to be confused with brands, which used to be called tenants.
+This feature is available from 2024.2 and is not to be confused with [brands](../core/brands.md), which were previously called tenants.
 ::::
 
-## Preparations
+## About tenants
 
-Starting with 2024.2, authentik allows an administrator or operator to create multiple tenants. This means that an operator can manage several authentik installations without having to deploy additional instances.
+Starting with version 2024.2, authentik allows an administrator or operator to create multiple tenants. This means that an operator can manage several different and distinct authentik installations, each with it's own Install ID and license(s). The relationships between tenant and installation (Install ID) is a 1:1 relationship, so for each tenant, there is a unique Install ID.
 
-Note that creating and managing tenants is handled using authentik APIs, not in the Admin interface.
+::::danger
+Expression policies currently have access to all tenants.
+::::
+
+The data for each tenant is stored in a separate PostgreSQL schema, providing full separation of user data. License data for the tenant is also stored in the schema.
+
+Note that creating and managing multiple tenants is handled using authentik APIs, not in the Admin interface. For typical authentik installations in which only a single tenant is needed, the default tenant is automatically created by authentik, and does not need to be managed in the Admin interface.
+
+### Licensing
+
+For each additional tenant (beyond the default one), one or more licenses is required; a license key cannot be used for more than one tenant. Note that the license for the default tenant must be valid and up-to-date in order to create additional tenants.
+
+A single tenant and its corresponding installation can have multiple license keys. For example, a company might purchase one license for 50 users, and then later in the same year need to buy another license for 50 more users, due to company growth. Both licenses are associated to the one installation, the one tenant.
+
+Learn more in our documentation about [Enterprise licenses](../enterprise/manage-enterprise#license-management).
+
+### Important considerations
+
+-   Upon creating another tenant, a new schema will be created by cloning the `template` schema. This special schema is like a tenant with no data created in it. Cloning an existing schema instead of creating a new one and running migrations on it is done for efficiency purposes.
+
+-   In a typical deployment, all data stored in Redis (such as tasks, locks, and cached objects) will have its keys prefixed by the `schema_name`.
 
-authentik manages tenants by storing data for each tenant in a separate PostgreSQL schema.
+-   Files are isolated on a per-tenant basis, with each tenant folder named according to the schema_name. For example, `/media/t_example`. The same is true regardless of the storage backend.
 
-This feature needs to be enabled with the `AUTHENTIK_TENANTS__ENABLED=true`. You also need to set `AUTHENTIK_TENANTS__API_KEY` to a random string, which will be used to authenticate to the tenancy API. This key will allow the creation of recovery keys for every tenant hosted by authentik, store it securely. You will also need to disable the embedded outpost with `AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true` as it is not supported with tenants.
+-   Using an [embedded outpost](../outposts/embedded/embedded.mdx) with multi-tenancy is not currently supported. Disable the embedded outpost with `AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true` configuration setting.
 
 ## Usage
 
-Tenants can be created using the API routes associated. Search for `tenant` in the [API browser](../../developer-docs/api/) for the available endpoints.
+To create one or more additional tenants (beyond the default tenant) use the following instructions.
 
-When creating a tenant, you must specify a `name`, used for display purposes, and a `schema_name`, used to create the PostgreSQL schema associated with the tenant. That `schema_name` must start with `t_` and not be more than 64 characters long.
+### 1. Configure authentik to allow multiple tenants
 
-There is always at least one tenant, `public`. This is the default tenant and cannot be deleted. Despite its name, it is not freely available to the world. Instead, it is stored in the `public` schema of the PostgreSQL database.
+First, enable the multi-tenancy feature with the `AUTHENTIK_TENANTS__ENABLED=true` [configuration setting](../installation/configuration.mdx).
 
-By default, all requests that do not explicitly belong to a tenant are redirected to the default tenant. Thus, after creating a tenant, you must associate a domain for which incoming requests will be redirected to said tenant. You can do so with API endpoints. After creating a domain `example.org` that is associated to the tenant `t_example`, all requests made to `example.org` will use the `t_example` tenant. However, requests made to `authentik.tld`, `subdomain.example.org` and all other domains will use the default tenant.
+Next, set `AUTHENTIK_TENANTS__API_KEY` to a random string. This string will be used to authenticate to the tenancy API. This key allows the creation of recovery keys for every tenant hosted by authentik, so be sure to _store it securely_. Be aware that creating a recovery key allows access to all data stored inside a tenant.
 
-::::warning
-Expression policies currently have access to all tenants.
-::::
+Be sure to disable the embedded outpost with `AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true` because it is not supported with tenants.
+
+### 2. Create a new tenant with authentik API endpoints
+
+Tenants are created using the API routes associated. Search for `tenant` in the [API browser](../../developer-docs/api/) for the available endpoints.
+
+When creating a tenant you must specify a `name`, used for display purposes, and a `schema_name`, used to create the PostgreSQL schema associated with the tenant.
+
+:::info
+The `schema_name` must start with `t_` and not be more than 64 characters long.
+:::
+
+There is always at least one tenant, `public`. This is the default tenant and cannot be deleted. Despite its name, it is not freely available to the world. Instead, it is stored in the `public` schema of the PostgreSQL database.
 
-## Notes
+### 3. Associate the new tenant with a domain
 
-Upon creating another tenant, a new schema will be created by cloning the `template` schema. This special schema is like a tenant with no data created in it. Cloning an existing schema instead of creating a new one and running migrations on it is done for efficiency purposes.
+By default, all requests that do not explicitly belong to a tenant are redirected to the default tenant. Thus, after creating a tenant, you must associate a domain for which incoming requests will be redirected to said tenant.
 
-Data stored in Redis (cache, tasks, locks) will usually get its keys prefixed by the `schema_name`.
+You can do so with API endpoints. After creating a domain `example.org` that is associated to the tenant `t_example`, all requests made to `example.org` will use the `t_example` tenant. However, requests made to `authentik.tld`, `subdomain.example.org` and any other domain that is not associated with the `t_example` tenant will use the default tenant.
 
-Files are stored by-tenant, under a `schema_name` directory. For example, `/media/t_example`. The same is true regardless of the storage backend.
+In summary, if you access a domain that is not explicitly associated with a specific tenant, it will be routed to the default tenant.