Tenants

---
name: "cipp-tenants"
description: "The top-level CIPP scope: enumerating managed M365 tenants, retrieving tenant detail, and the accepted `tenantFilter` identifier formats (default domain, custom domain, GUID, `allTenants`). Also covers stale-cache detection and the two common tenant-resolution failure modes."
when_to_use: >-
  When listing managed M365 tenants, looking up tenant IDs/domains, or scoping operations across
  the MSP portfolio. Use when: cipp tenant, list tenants, m365 tenant, tenant details, which
  tenants, all tenants, cipp portfolio, or msp tenant list.
---

# CIPP Tenants

Tenants are the top-level scope in CIPP. Every operational tool — users, mailboxes, standards, security — takes a `tenantFilter` parameter that scopes the call to one tenant or to `allTenants`. Knowing how to enumerate tenants and resolve a friendly name to its tenant ID is the first step in almost every CIPP workflow.

## Anti-triggers

- **Inforcer's tenant list** — Inforcer manages the same M365 tenants
  but keys them by an *integer* Client Tenant ID, not a domain or GUID.
  A `tenantFilter` value from here will not work there; use
  `inforcer-tenant-management`.
- **Why a tenant is missing, stale, or failing** — that is usually the
  GDAP delegation chain, not the tenant record; use `cipp-ops`.
- **A tenant's licence, standards, or CA posture** — this skill only
  resolves and describes the tenant itself; use `cipp-licenses`,
  `cipp-standards`, or `cipp-security`.

## Tools

### `cipp_list_tenants`

List every tenant CIPP manages. Returns a list of tenant objects with `customerId`, `defaultDomainName`, `displayName`, and onboarding status.

```
cipp_list_tenants()
```

Use this whenever a user refers to a client by name — the response gives you the `defaultDomainName` (or `customerId`) needed for `tenantFilter` on every other tool.

### `cipp_get_tenant_details`

Retrieve detailed information for one tenant: license count, domain list, GDAP relationship status, last refresh time.

```
cipp_get_tenant_details(tenantFilter='contoso.onmicrosoft.com')
```

Use `tenantFilter='allTenants'` to get a portfolio-wide aggregate — useful for fleet reports.

## Identifying a tenant

Most CIPP tools accept any of these in `tenantFilter`:

| Format | Example | Notes |
|--------|---------|-------|
| Default domain | `contoso.onmicrosoft.com` | Most readable, recommended |
| Custom domain | `contoso.com` | Works if CIPP has it cached |
| Tenant GUID | `00000000-0000-0000-0000-000000000000` | Most stable but opaque |
| `allTenants` | `allTenants` | Portfolio-wide; only some tools support it |

When a user says "Acme", always run `cipp_list_tenants` first and resolve to the canonical `defaultDomainName` before calling other tools. Never guess the tenant identifier.

## Common patterns

**Resolve a friendly name → tenant filter**

```
tenants = cipp_list_tenants()
acme = next(t for t in tenants if 'acme' in t['displayName'].lower())
tenant_filter = acme['defaultDomainName']
```

**Audit which tenants are stale in CIPP cache**

`cipp_get_tenant_details` returns `lastRefresh`. Tenants not refreshed in >24h often signal a broken GDAP relationship or revoked consent — flag them before running standards or BPA checks against them.

## Failure modes

- **`tenantFilter` not found** — the tenant exists in M365 but CIPP hasn't onboarded it. Trigger a tenant cache refresh in CIPP UI or check GDAP roles.
- **Empty tenant list** — the API client has no tenant scope assigned. Check the role assigned to the API client in CIPP Settings → API Client Management.