Skip to content

Managing tenants

The Tenants page is where you create, review, edit and remove the identity tenants of a workspace. Open it from Tenants in the sidebar.

Every workspace member can open the page. Only admins can create, edit or delete a tenant.

The page title is Tenants, with the description “Create, monitor, and manage identity tenants for this workspace.” It is one page with stacked sections, from top to bottom:

  1. A trial banner, only when it applies. See Tenant health.
  2. Create a tenant: three cards.
  3. Tenant topology: a live picture of the tenants.
  4. Manage existing tenants: the Tenant overview table.
Card Caption Guide
Okta Workforce identity Connect Okta
Auth0 Customer identity Connect Auth0
Entra ID Microsoft ecosystem Connect Microsoft Entra ID

Admins choose Connect on a card. Members and viewers see “Only workspace admins can create tenants.” and a disabled Admin Access Required button on each card.

Each plan allows a number of tenants per workspace.

Plan Tenants per workspace
Pro 3
Max 10
Super 25

The Tenants page does not warn you when the workspace is at the limit, and the Connect buttons stay active. You learn about the limit when you submit the create form: “Failed to create tenant: The <Plan> plan allows up to N tenants per workspace, and this workspace already has M. Upgrade the plan to add more.” Delete a tenant or upgrade the plan. See Plans and billing.

The card Manage existing tenants (“Review configured tenants, update integrations, and remove tenants when decommissioning access.”) holds the Tenant overview table.

Control What it does
Search tenants… Filters by tenant name or type. The table returns to page 1.
Name, Type, Created column headers Select a header to sort. Select it again to reverse the order.
Type badge Shows okta, auth0 or microsoft. An Entra ID tenant shows as microsoft.
Actions column Icon buttons, described below.
Page buttons, Previous page, Next page The table shows 5 tenants per page. The footer reads Showing X to Y of N tenants.

The actions are icon buttons with tooltips. There is no text button and no menu.

Icon Tooltip Shown on Who can use it
Pencil Edit Every row Admins. Others see the tooltip “Admin access required to edit tenant” and a disabled button.
Line chart API Metrics Auth0 rows only Everyone. See Auth0 API metrics.
Bin Delete tenant Every row Admins. Others see the tooltip “Admin access required to delete tenant” and a disabled button.
What you see Meaning
No tenants added yet with “Add a tenant using the options above to get started.” The workspace has no tenants.
No tenants match your search with “Try a different name or tenant type.” The search box filters out every tenant.

The Tenant topology card (“Animated view of tenant integrations connected to the Identiguard control plane.”) is a picture, not a control. Nothing in it can be selected, and it has no legend or tooltips.

Element Meaning
Header “Avg requests per minute per tenant (last 24h)” What the labels on the tenants measure
Badge Live view (green) or Refreshing… Whether the figures are loaded or loading
Centre node Identiguard, “N connected tenant(s)”, “control plane” The workspace, with the number of tenants
One coloured node per tenant, with its name and “X req/min” The tenant and its traffic
Node Alex AI at the top right The state of the Ask Alex service: “AI service · Online” (green), “AI service · Offline” (red) or “AI service · Checking…” (amber). It shows “Last seen <time>” when known.
“+N more tenants not shown in this preview.” The picture draws 12 tenants at most
“No connected tenants to display yet.” The workspace has no tenants

The topology is not a health view. A tenant with broken credentials looks the same as a healthy one, except that it may show “0 req/min”. See Tenant health.

Choose the pencil icon (Edit) on a row to open Edit Tenant. Only admins can open it.

The page has one or two cards:

  • Tenant Configuration (“Update tenant details, subscriptions, and monitoring preferences.”), with the buttons Save Changes and Cancel. Every provider has it.
  • Credentials, with its own button Validate & save credentials. Okta and Entra ID only.

Save Changes saves everything in Tenant Configuration. The button reads Saving… while it works. On success you return to the Tenants page. On failure a banner titled Error appears at the top of the Edit page. Back to Tenants and Cancel leave without saving.

Sections by provider:

Section Okta Auth0 Entra ID
Basic Details Yes Yes Yes
Event Subscriptions Yes Yes Yes
Reporting permissions (optional) No No Yes
Agent Monitoring Yes No No
Credentials card Yes No Yes

Every provider has Tenant Name and Customer Name (placeholder “Select or type a customer”, with suggestions from the workspace). The tenant name follows the same rules as at creation: required, 100 characters or fewer, no line breaks.

You cannot change the domain or directory of a tenant, for any provider. Delete the tenant and create it again.

Okta adds:

  • Environment: Production or Development.

Entra ID adds:

  • Poll Interval (Minutes): from 5 to 1440 (24 hours). The create form stops at 60, so this is where you set a longer interval.

Auth0 shows read-only values:

Item What it shows
Auth0 Domain The tenant’s domain
Provisioning Manual or Deployed via Terraform
Log stream endpoint The endpoint URL only. The token is never shown again.
Text “Identiguard stores no Auth0 API credentials for this tenant.” The log stream is managed in the Auth0 dashboard or in your Terraform configuration. To change the domain, delete and recreate the tenant.
Manual tenants “Connection details are read-only. To change the domain or credentials, delete and recreate the tenant.”
Terraform tenants A box identiguard.tf with View Terraform configuration and Hide Terraform configuration, and a Copy button (toast “Terraform configuration copied to clipboard”). A note says the ingestion token is not in this file. It was shown once at creation. If it is lost, delete and recreate the tenant.
Synthetic journeys A summary of the tenant’s journeys, or “Synthetic journey monitoring is available on Max and Super plans.” when journeys are not switched on for the workspace. See Journeys.

The Auth0 Edit page has nothing for the metric stream or for Action logs. See Connect Auth0.

This section is how you change which events a tenant sends after creation. It has the same picker as the create form, under the label Subscribed Event Types.

Control What it does
Search event types… Filters the list. Shown when the list has more than 10 types.
Select Recommended Auth0 only. Replaces the whole selection with the recommended set.
Select All Ticks every type. While you search, it becomes Select All Visible.
Clear All Unticks everything.
N of M selected The current count. At least one type must be ticked.

What saving does is different for each provider:

Provider On-screen text Effect of Save Changes
Okta “Updating this list changes the Okta event hook immediately.” Identiguard rewrites the event hook in the Okta org at once.
Entra ID “Updating this list changes the Microsoft subscription immediately.” Identiguard polls the new set of streams from the next poll.
Auth0 “Updating this list changes which Auth0 log events are ingested. Takes effect immediately; no changes are made in Auth0.” Only what Identiguard keeps changes. The Auth0 stream still sends everything it is configured to send.

For the task steps, see Change which events a tenant sends.

Reporting permissions (optional) checks the app registration live each time the page loads. The on-screen instruction reads “Add these as application permissions on the app registration in the Entra admin centre, then select Grant admin consent.”

Each of six rows shows Granted or Not granted:

Permission Used for Also counts as granted with
Reports.Read.All MFA coverage (also needs Entra ID P1) AuditLog.Read.All
RoleManagement.Read.Directory Global Administrator count RoleManagement.Read.All or Directory.Read.All
Policy.Read.All Conditional Access inventory
Application.Read.All App credential expiry Directory.Read.All
SecurityEvents.Read.All Microsoft Secure Score
IdentityRiskyUser.Read.All Current risky users

To fix a Not granted row:

  1. In the Entra admin centre, open the app registration and go to API permissions.
  2. Add the missing Microsoft Graph application permission.
  3. Choose Grant admin consent.
  4. Reload the Edit page. There is no refresh button.

Agent Monitoring (“Track AD and LDAP agent health on a recurring schedule.”) has two panels: Monitor AD Agents and Monitor LDAP Agents. It needs the Okta scope okta.agentPools.read.

To switch a monitor on or off, or to change its interval:

  1. Open Tenants and choose the pencil icon (Edit) on the Okta tenant.
  2. Under Agent Monitoring, tick or untick Monitor AD Agents and Monitor LDAP Agents.
  3. For each ticked monitor, choose Check Interval (minutes): 5, 10, 15, 30, 60 or 120. While a monitor is unticked, the helper reads “Enable monitoring to configure the check interval.”
  4. Choose Save Changes.
  5. Open the Edit page again, or look at the tenant’s card on the Dashboard, and read Status: and Last check:.

Opening the Edit page runs a fresh check of each monitor that is on. For the meaning of each status, see Tenant health.

The Credentials card (“Rotate the client secret (and optionally the client ID) used to connect to Okta.” or “…to Microsoft.”) is a separate form. Save Changes does not submit it.

Item Detail
Heading Rotate credentials “New credentials are verified against Okta before being saved.” (or Microsoft)
Client ID (optional) Placeholder “Enter new client ID (leave blank to keep current)”
Client Secret Placeholder “Enter new client secret”
Button Validate & save credentials Reads Validating… while it checks
Alert Verified “Credentials updated and verified against Okta.” or “…against Microsoft.”
Alert Credentials rejected The reason. Nothing was saved.
Alert Monitoring paused Shown when a monitor has paused itself. See Tenant health.

For the steps, see Rotate credentials.

  1. Open Tenants and choose the pencil icon (Edit).
  2. Under Basic Details, change Tenant Name or Customer Name. For Okta you can also change Environment.
  3. Choose Save Changes.
  1. Open Tenants and choose the pencil icon (Edit) on the Entra ID tenant.
  2. Under Basic Details, set Poll Interval (Minutes) from 5 to 1440.
  3. Choose Save Changes.

A longer interval means events arrive later.

Only admins can delete a tenant. Deleting cannot be undone. It removes the tenant’s stored data from Identiguard: its event history, its reports and its monitor state. It also revokes the tenant’s ingestion tokens.

  1. Open Tenants.
  2. In Tenant overview, choose the bin icon (Delete tenant) on the row.
  3. Read the dialog Delete tenant: <name>. It says what Identiguard does and does not remove on the provider side.
  4. Choose the red Delete tenant button, or Cancel.
  5. Accept the browser’s confirmation prompt.

The dialog closes and the table refreshes.

Provider What Identiguard does What you must do afterwards
Okta Deactivates and removes the Okta event hook, then deletes the tenant. The dialog shows the Event Hook ID so you can check the clean-up in Okta. It can read “Loading…” or “Event Hook ID not available”. Remove the Identiguard integration in Okta if the client is leaving.
Auth0, manual Nothing in Auth0. Identiguard stores no Auth0 credentials and cannot remove the streams. Delete the log stream, and the metric stream if there is one, in the Auth0 dashboard.
Auth0, Terraform Nothing in Auth0. Run terraform destroy, or delete the log stream in Auth0.
Entra ID Stops polling Microsoft Graph. Nothing is changed inside the Entra ID tenant. Revoke the app registration’s secret if you no longer need it.

Force delete tenant is not a standing option. It appears only inside the dialog, and only after a normal delete fails because Identiguard could not remove the Okta event hook. In practice it applies to Okta tenants only.

  1. A normal delete fails with “Failed to delete tenant: Failed to remove Okta event hook.”
  2. The dialog shows a red box Could not remove the Okta event hook: “Looks like the event hook has already been deleted on Okta, or Okta is not responding. You can force delete this tenant instead - its stored data (including event history) will be removed from Identiguard without making any further changes in Okta.”
  3. The button changes to Force delete tenant. Choose it.
  4. Accept the browser’s confirmation prompt.
  5. In Okta, go to Workflows → Event Hooks. If the IG_Tenant_ hook for this tenant still exists, deactivate and delete it yourself.
What you see Why What to do
“Could not load tenants.” The tenant list failed to load Reload the page. Check that you still have access to the workspace.
“Only workspace admins can create tenants.” and Admin Access Required Your role is member or viewer Ask a workspace admin.
Disabled pencil or bin with “Admin access required to edit tenant” or “Admin access required to delete tenant” Your role is member or viewer Ask a workspace admin.
No line-chart icon on a row API Metrics exists for Auth0 tenants only Nothing.
An Entra ID tenant shows microsoft The Type badge shows the stored type Nothing. Search for microsoft to find Entra ID tenants.
No message after you create or edit a tenant The Tenants page does not show a confirmation Check the row in Tenant overview.
“Failed to create tenant: The <Plan> plan allows up to N tenants per workspace, and this workspace already has M. Upgrade the plan to add more.” The plan tenant limit Delete a tenant or upgrade the plan.
“0 req/min” for every tenant in the topology No events in 24 hours, or the traffic figures failed to load Reload the page, then check the Dashboard.
“AI service · Offline” in the topology The Ask Alex service is not answering See Ask Alex.

These appear in the Error banner at the top of the Edit page.

What you see Why What to do
“At least one event type must be selected” Nothing is ticked under Subscribed Event Types Tick at least one.
“Invalid Microsoft event type submitted” or “Invalid Auth0 event type submitted” The page sent a type that is not on the allowed list Reload the page and select again.
“Customer name cannot be empty” Customer Name was cleared Enter the customer.
“At least one field (…) must be provided for update.” The form was sent with nothing to change Change a value, then save.
“Failed to update Okta event hook: <Okta message>” Okta rejected the hook update. Common causes: the secret has expired, or a scope is missing. Rotate the credentials first, then save again.
“Okta event hook ID missing from configuration; recreate the event hook before updating.” The tenant has no stored hook ID Delete the tenant and create it again. There is no screen to recreate the hook alone.
“Okta tenant configuration missing encrypted secrets; recreate the event hook before updating.”, “Failed to decrypt Okta credentials. Please recreate the event hook and try again.” or “Okta configuration is missing client details; please recreate the tenant.” The stored credentials cannot be used Delete the tenant and create it again. Escalate to the product team.
“Failed to update Auth0 tenant: <message>”, “Failed to update Microsoft tenant: <message>” or “An unexpected error occurred: …” A server error Try again, then escalate.
“Forbidden: Insufficient permissions. Admin role required to update tenant.” You are not an admin Ask a workspace admin.
“Editing is not supported for this tenant type.”, “Tenant not found” or “Internal Server Error” An unexpected error Escalate to the product team.
“Could not load reporting permissions.” The permission check failed to load Reload the page.
“Could not read the app registration permissions. Check the tenant credentials.” Identiguard could not sign in to read the app registration Rotate credentials, then reload.
Not granted on a reporting permission The permission is missing, or admin consent is not granted Add the permission, choose Grant admin consent, reload the page.
“Synthetic journey monitoring is available on Max and Super plans.” Journeys are not switched on for the workspace Needs the Max or Super plan, and a platform operator switches journeys on for the workspace.
A locked agent checkbox with “Monitoring paused after repeated failures - rotate the credentials below to resume.” The monitor paused itself Rotate credentials.
Alert Credentials rejected The new credentials failed the check See Rotate credentials.
What you see Why What to do
“Failed to delete tenant: Failed to remove Okta event hook.” and the box Could not remove the Okta event hook Okta refused or did not answer. The hook may already be deleted, the credentials may be revoked, or Okta may be down. Choose Force delete tenant. Then remove the hook in Okta by hand if it still exists.
“Failed to delete tenant: Failed to cleanup tenant event history.”, “Failed to delete tenant: Failed to cleanup tenant monitor state.” or “Failed to delete tenant: Failed to delete tenant report artifacts.” An internal clean-up step failed. Force delete is not offered for these. Try again. If it repeats, escalate to the product team.
“Failed to delete tenant: API Error”, “An unexpected error occurred.” or “Failed to delete tenant.” An unexpected server error Try again, then escalate.
“Forbidden: Insufficient permissions. Admin role required.” You are not an admin Ask a workspace admin.
“Event Hook ID not available” in the dialog The tenant has no stored hook ID For information only. You can still delete.
Auth0 shows delivery failures on the stream after the delete The stream still points at the revoked endpoint Delete the stream in Auth0, or run terraform destroy.