analysis

Access analysis scans a tenant's configuration for risky or stale access, such as administrators without MFA or dormant accounts that still hold roles. It also reports API keys nobody uses, broken manager links, and more. It answers "what should we fix first?" without anyone reading every policy by hand, and a policy linter catches documents that do not do what their author intended. Nothing here changes access: findings are observations you act on through the other groups, or suppress with a recorded reason when a risk is accepted.

What the scan checks

findings runs every check below in one read-only transaction. "Administrator" means a tenant owner or anyone who holds a role that grants every action (* or iam:*) on every resource without conditions. Protected system policies and the Owner role are not reported against.

Each finding has a title, a detail that says what to do, and the subject it concerns (a policy, role, identity, group, trust, credential, delegation, team, or department).

Suppressing findings

Some findings describe accepted risk: a break-glass administrator account, or a service account that must be powerful. Suppress them with a reason so they stop cluttering the results. Finding IDs are deterministic: the same condition on the same subject always yields the same 24-character ID, so a suppression keeps applying for as long as the condition holds, and again if it returns later. Suppressed findings are counted in summary.suppressed and listed, with who suppressed them, when, and why, when you pass includeSuppressed: true.

findings

Runs every access-analysis check on the tenant and returns the findings, most severe first, with counts per severity.

Used inEnterprise onboarding,Access reviews

• Permission: iam:analysis:read on iam/analysis/*.
• Audited as: iam:analysis:read.
• Errors: INVALID_INPUT when dormantDays is outside 1 to 3650.

dormantDays (default 90) sets when an unused account, API key, or eligible binding is reported. Suppressed findings are left out unless includeSuppressed is true. Run it on a schedule and alert on new high findings; the analyze CLI command does this with --fail-on high, which suits a CI or cron job.

const { summary, findings } = await iam.api.analysis.findings(credential, { tenantId, dormantDays: 60 });
for (const finding of findings.filter((item) => item.severity === 'high'))
  console.log(finding.title, finding.detail);

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

iam.api.analysis.findings(
  credential: CredentialInput,
  input: { tenantId: string; dormantDays?: number; includeSuppressed?: boolean },
): Promise<{
  generatedAt: number;
  dormantDays: number;
  summary: { high: number; medium: number; low: number; suppressed: number };
  findings: AccessFinding[];
}>

lintPolicy

Checks a policy document, or a stored policy, for errors and for statements that likely do not do what they say.

• Permission: iam:policies:read on the policy (with policyId) or on the tenant (with a candidate document).
• Audited as: iam:policies:read.
• Errors: INVALID_INPUT unless exactly one of document and policyId is given; NOT_FOUND when the policy is not in this tenant.

The document is first validated the way storage would validate it, including unknown actions and resource types. A document storage would reject is not thrown as an error: the result has valid: false, the error code and message, and no warnings. A valid document gets warnings, each with a code, a severity (warning: probably a mistake; info: worth a look, often intended), the statement index, and a message. Examples include an allow that makes every holder a full administrator, a condition key the server never sets, a deny that silently never applies when an optional key is missing, an allow that an unconditional deny shadows, and duplicate statements.

Use it in a policy editor before saving, or in CI over documents kept in version control. Pass contextKeys to name keys your application supplies through resolveContext, so they are not reported as unknown. See policies and conditions.

const result = await iam.api.analysis.lintPolicy(credential, {
  tenantId,
  document: {
    version: 1,
    statements: [{ effect: 'allow', actions: ['documents:*'], resources: ['*'] }],
  },
});
// result.valid === true; result.warnings[0].code === 'service-wildcard'

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

iam.api.analysis.lintPolicy(
  credential: CredentialInput,
  input: {
    tenantId: string;
    document?: unknown;
    policyId?: string;
    contextKeys?: string[];
  },
): Promise<PolicyLintResult>

suppress

Hides one finding from future results and records why.

• Permission: iam:analysis:update on iam/analysis/{findingId}.
• Audited as: iam:analysis:update.
• Errors: INVALID_INPUT when findingId is not a 24-character finding ID, or reason is empty or longer than 500 characters.

The reason, the caller, and the time are kept and shown to anyone who lists suppressed findings, so reviewers can see who accepted which risk. Suppressing a finding again replaces its reason.

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

iam.api.analysis.suppress(
  credential: CredentialInput,
  input: { tenantId: string; findingId: string; reason: string },
): Promise<{ suppressed: boolean }>

unsuppress

Shows a suppressed finding again.

• Permission: iam:analysis:update on iam/analysis/{findingId}.
• Audited as: iam:analysis:update.

Unsuppressing a finding that is not suppressed succeeds and changes nothing.

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

iam.api.analysis.unsuppress(
  credential: CredentialInput,
  input: { tenantId: string; findingId: string },
): Promise<{ suppressed: boolean }>