reports

The access report gathers a tenant's access-lifecycle state in one document: what is about to end, who is elevated right now, and which API keys nobody uses. Temporary access only stays safe if someone notices what is expiring, what is pending, and what was forgotten, and checking each list by hand does not scale. Run the report nightly and route it to a channel or ticketing system. See the access report.

access

Returns the tenant's access report: identities and grants ending soon, live elevations, pending requests, and unused or expiring API keys.

Used inAccess report

• Permission: iam:identities:read on the tenant. The bindings section also needs iam:bindings:read and the credentials section iam:credentials:read on the tenant; without them the section is left out, not refused.
• Audited as: iam:identities:read.
• Errors: INVALID_INPUT when withinMs or unusedForMs is negative or longer than ten years.

withinMs (default 30 days) is the look-ahead window for things that end or start, and unusedForMs (default 30 days) is how long an API key must go unused to be listed. The report has three sections:

• identities: how many identities the tenant has (deleted ones excluded) and how many are disabled, plus people and service accounts whose expiresAt falls within the window. An identity already past its deadline stays listed with expired: true until the retention worker disables it.
• bindings: how many unexpired bindings there are, and how many of them are eligible or limited to an access window; bindings that expire within the window; future-dated bindings that start within it; temporary group memberships that end within it; live just-in-time activations with their justification; and the number of activation requests awaiting a decision.
• credentials: the number of unexpired API keys, keys not used for unusedForMs (never-used keys count from their creation), and keys that expire within the window.

omitted names the sections the caller could not read, so a directory administrator without iam:credentials:read still gets the rest. For email delivery to tenant owners, schedule iam.sendAccessDigest() instead; the report CLI command prints the same report.

const report = await iam.api.reports.access(credential, { tenantId, withinMs: 14 * 24 * 60 * 60 * 1000 });
for (const binding of report.bindings?.expiring ?? [])
  console.log(`${binding.subjectName ?? binding.subjectId} loses ${binding.roleName ?? binding.roleId}`);

curl -X POST "$IAM_URL/api/iam/reports/access" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.reports.access(
  credential: CredentialInput,
  input: { tenantId: string; withinMs?: number; unusedForMs?: number },
): Promise<AccessReport>