Checking decisions

check() is the core operation: it asks the server “may this subject perform this permission on this
resource?” and returns a normalized Decision. This guide covers building the query,
reading the answer, and the fail-closed contract around it.

Motivation

You want a single, unambiguous yes/no for an action, with the policy decision made centrally on the
server. The client must never invent an “allow” — if it cannot reach the server or cannot understand the
answer, the only safe response is deny.

The call

use laravel_iam::{IamClient, DecisionQuery, Subject, ResultExt};
use serde_json::json;

let decision = iam.check(DecisionQuery {
    subject: Subject::user("usr_123"),
    application: Some("warehouse".into()),
    permission: "stock.adjust".into(),
    resource: Some("wh_milan".into()),
    context: json!({ "amount": 300 }),
    ..Default::default()
}).await;

if !decision.is_allowed() {
    // deny
}

check() performs POST {base_url}/decisions/check with Accept: application/json and, when a token is
configured, Authorization: Bearer <token>.

Building the query

DecisionQuery implements Default, so use struct-update syntax and only set what
you need:

There is also a convenience constructor for the common case:

// subject + permission, everything else defaulted
let q = DecisionQuery::new(Subject::user("usr_123"), "stock.adjust");

Reading the answer

For a gate, read ResultExt::is_allowed and stop there. When you need detail, match on
the Ok:

use laravel_iam::{Decision, IamError};

match iam.check(query).await {
    Ok(d) if d.granted()        => grant(),
    Ok(d) if d.requires_step_up => prompt_step_up(d.required_aal),
    Ok(_)                       => deny("policy denied"),
    Err(IamError::Timeout)      => deny("iam timeout"),
    Err(e)                      => deny(&format!("iam error: {e}")),
}

A Decision carries:

Defensive parsing

The response is parsed with the same rules as the PHP IamDecision::fromArray:

• A non-2xx status is an error before the body is even read — see the check flow.
• A body that is not a JSON object is IamError::Malformed → deny.
• Any individual field that is missing or wrong-typed falls back to its safe default
  (allowed → false, policy_version → 0, etc.).
• allowed is true only when the server sent the boolean true.

So a successful HTTP 200 with { "decision_id": "x" } (no allowed) parses cleanly to a deny.

Worked example: a step-up sensitive action

use laravel_iam::{DecisionQuery, Subject};
use serde_json::json;

let query = DecisionQuery {
    subject: Subject::user("usr_123"),
    application: Some("banking".into()),
    permission: "wire.transfer".into(),
    resource: Some("acct_42".into()),
    context: json!({ "amount": 50_000, "currency": "EUR" }),
    current_aal: "aal1".into(),
    explain: true,
    ..Default::default()
};

match iam.check(query).await {
    Ok(d) if d.granted() => execute_transfer(),
    Ok(d) if d.requires_step_up => {
        // The user is allowed in principle but must re-auth at a higher level.
        redirect_to_step_up(d.required_aal.as_deref().unwrap_or("aal2"));
    }
    _ => deny(), // explicit deny OR any error — fail-closed
}

Gotchas

See also: Listing resources, Fail-closed patterns.