Docs

Evaluate a policy

POST
/policies/evaluate

Evaluates a policy config against one request, without side effects, and answers the decision the operation would reach. Nothing is read from or written to the project: the config is the one in the body, checked exactly as a publish checks it, so an invalid config answers pol.invalid with the same violations.

input is what the operation's request carries, in the operation's own terms (a password, not its length): the server derives what the policy checks with the code the live operation runs, guards included. facts states what the operation would look up at runtime, such as whether the candidate matches one of the user's kept passwords.

The decision and the names of the failed rules hold wherever the operation runs. code and violations are what an API call answers; a login flow shows the same rules as field errors on the password field (error.x-auth-methods#password_<rule> in step.error).

Which policy a project or release applies is not decided here: read it and pass its config.

The caller needs read access to the project in project_id.

Authorization

headerAuthorizationBearer <token>

Scope: policy.read

Query Parameters

project_id*string

The unique identifier of the project

Match^[a-zA-Z0-9_-]+$

Request Body

application/json
  1. body

A dry run of the password policy for one candidate password.

operation*"auth.factor.password.set"

The operation the policy guards.

Value in"auth.factor.password.set"
config*

The settings of an auth.factor.password.set policy. Every setting is optional; a setting left out switches its rule off, and {} switches every rule off. There are no defaults. The bounds are technical limits, not recommendations; the server's template checks the same bounds.

input*

The password as a user or administrator would set it. The server derives what the policy checks (its length in code points after NFC normalization) with the same code a password set runs.

facts?

What a password set looks up instead of reading from the request. A dry run has no user, so it is stated here.

Response Body

The policy was evaluated.

application/json
  1. response

The decision the operation would reach for the request. A refusal carries the error code and violations an API call of the operation would answer with; a login flow shows the same rules as field errors instead.

allowed*boolean

Whether the operation would go ahead.

code?string

The error code an API call of the operation would answer with, set only when it would refuse, for example user.password_empty or user.password_policy_violation.

violations?

Every failed rule keyed by name with the value of the setting it is named after, e.g. {"min_length": 12}, as the live error's details.violations. Set only with user.password_policy_violation.

import { configureZitadel, getApi } from "@zitadel/api/config";import { setApiCsrfToken } from "@zitadel/api/runtime/auth";// In the browser, through the SDK proxy: the session cookie authenticates the call.const client = getApi(configureZitadel({ projectId: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" }));// A write the session cookie authenticates carries the session's CSRF token.setApiCsrfToken((await client.getMySessionCsrfToken()).csrf_token);const result = await client.evaluatePolicy(  {    operation: "auth.factor.password.set",    config: { min_length: 12 },    input: { password: "short1" },  },  { project_id: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" },);
Example Response
{  "allowed": true}

Was this helpful?