iam.policies.simulateTest whether a user, role or draft policy allows an action, and why
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
principalOptionalobject
The user or role to test, as {type: user|role, id}; omitted: only policyDocuments are evaluated
Constraints: JSON
policyDocumentsOptionalarray 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
actionRequiredstring
The one action to test, e.g. ec2:StartInstances (not a pattern)
Constraints: 3-128 chars, /^[a-z0-9-]+:[A-Za-z0-9]+$/
resourceRequiredstring
The resource name (RN) the request would act on, or *
Constraints: 1-1024 chars, /^(\*|rn:(?:dcloud|ews):[^\s]*)$/
contextOptionalobject
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 examplecurl -X POST "https://console.platform-development.deutschecloud.app/iam/api/simulate" \
-H "Authorization: EWS-ACCESS-KEY $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"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.