# reports (/docs/reference/api/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.



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](/docs/guides/privileged-access/access-report).

| Method              | What it does                                                                                                                               | Access     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| [`access`](#access) | Returns the tenant's access report: identities and grants ending soon, live elevations, pending requests, and unused or expiring API keys. | Credential |

## access [#access]

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

**HTTP:** `POST /api/iam/reports/access` (requires a credential) · **Browser client:** `client.reports.access()`

* **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()`](/docs/reference/api#sendaccessdigest) instead; the `report`
[CLI command](/docs/reference/cli#report) prints the same report.

```ts
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}`);
```

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