iam.policies.simulate

Test whether a user, role or draft policy allows an action, and why

POST /iam/api/simulateIAM iam:SimulatePrincipalPolicyRead

Give `principal` ({type: user|role, id}), `policyDocuments` (JSON strings, not saved), or both — drafts are then evaluated as if attached. A principal needs iam:SimulatePrincipalPolicy on it, drafts need iam:SimulateCustomPolicy. The answer names the deciding statement, its policy and how that policy reaches the principal (directly, group, role). `context` sets condition keys (sourceIp, multiFactorAuthPresent, currentTime, requestedRegion, availabilityZone, requestProject, resourceProject); a key left out is unknown, as it would be for a request that does not carry it. Bucket policies of S3 are not included.

Depending on the resource, the call checks iam:SimulateCustomPolicy instead; hold all of them to be sure it is allowed.

Request syntax

POST /iam/api/simulate
{
  "principal": "object",
  "policyDocuments": "array of string",
  "action": "string",
  "resource": "string",
  "context": "object"
}

Request body

  • principalOptional

    object

    The user or role to test, as {type: user|role, id}; omitted: only policyDocuments are evaluated

    Constraints: JSON

  • policyDocumentsOptional

    array of string

    Policy documents (JSON text) that are not saved: with a principal, evaluated as if attached to it; without one, on their own

    Constraints: 2-65536 chars

  • actionRequired

    string

    The one action to test, e.g. ec2:StartInstances (not a pattern)

    Constraints: 3-128 chars, /^[a-z0-9-]+:[A-Za-z0-9]+$/

  • resourceRequired

    string

    The resource name (RN) the request would act on, or *

    Constraints: 1-1024 chars, /^(\*|rn:(?:dcloud|ews):[^\s]*)$/

  • contextOptional

    object

    Condition keys of the imagined request: sourceIp, multiFactorAuthPresent, currentTime (default now), requestedRegion (default your region), availabilityZone; a key left out is unknown

    Constraints: JSON

Response

200 with decision (allowed, explicitly_denied or implicitly_denied), summary, action, resource, statements (those whose Action matches, deciding ones first, each with its policy and how it reaches the principal), policiesEvaluated, notes, principal ({ type, id, name, status } or null) and context (the condition key values used).

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow iam:SimulatePrincipalPolicy on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud iam policies simulate --action example --resource example

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_iam_policies_simulate.