Skip to main content

explainPolicy

Render a policy spec — the same input shape as createGroupPolicy — as a list of plain-English sentences describing what it permits or blocks.

The explanation reflects the engine's scope-aware evaluation: a condition whose attribute key isn't reachable from a given action's entity is dropped before rendering, which can widen that action to be unconditional. Pair this with the policy editor so authors see exactly what the policy will allow before saving.

Conditions referencing undeclared custom attribute keys are silently ignored — the explainer is lenient by design, so typos surface as a "wider than expected" sentence rather than a hard error.

Example input:

{
  effect: ALLOW
  actions: ["project:create", "project:update", "environment:create"]
  conditions: "{\"md-environment\":[\"dev\",\"staging\",\"prod\"]}"
}

Example output:

[
  "Can create environments with identifiers [dev, staging, prod].",
  "Can create and update any project."
]
explainPolicy(
  organizationId: ID!
  input: CreateGroupPolicyInput!
): [String!]!

Arguments​

explainPolicy.organizationId ● ID! non-null scalar {#organization-id}​

Your organization's unique identifier.

explainPolicy.input ● CreateGroupPolicyInput! non-null input {#input}​

The policy spec to explain — same shape as the createGroupPolicy input.

Type​

String scalar​

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.