git:20260713.1fbd3f3 to git:20260728.b7e78fc

1 added, 1 removed. Audit A to A.

---

name: "cipp-tenants"

- description: "Use this skill when working with CIPP tenants — listing managed M365 tenants, checking tenant details, identifying tenant ID/domain, and scoping operations to a specific tenant. The starting point for almost every CIPP workflow since most other tools require a tenant filter."

+ 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.

## 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.