indykite-authzen-evaluation

IndyKite AuthZEN - single authorization decision

A KBAC decision asks the AuthZEN endpoint one question - may this subject perform this action on this resource? - and gets back a boolean decision. The decision is rendered by evaluating the project's currently ACTIVE 2.0-kbac policies against the IKG.

This skill covers making that single decision: framing the (subject, action, resource, context) request, sending it, and reading the boolean. It does not author policies - the policy whose subject / actions / resource / condition.cypher the decision is evaluated against is authored with indykite-authzen-kbac.

It is the single-call member of the AuthZEN family:

Need	Endpoint	Skill
One yes/no decision	/access/v1/evaluation	this skill
Many decisions at once	/access/v1/evaluations	indykite-authzen-evaluations
Actions a subject may perform on a resource	/access/v1/search/action	indykite-authzen-search-action
Resources a subject may act on, given an action	/access/v1/search/resource	indykite-authzen-search-resource
Subjects allowed an action on a resource	/access/v1/search/subject	indykite-authzen-search-subject
Author / manage the KBAC policy	Config API	indykite-authzen-kbac

When to use

Activate this skill when the user wants to:

• decide whether one subject may perform one action on one resource (e.g. "can ada PROVISION the server gpu-node-7 within a budget of 120000?");
• gate an operation in an application on a live authorization check;
• debug why a single decision comes back true or false.

Do not activate this skill to author or modify the policy behind the decision (indykite-authzen-kbac), to make many decisions in one call (indykite-authzen-evaluations), to enumerate the allowed actions/resources/subjects rather than test one triple (the search skills -search-action / -search-resource / -search-subject), or to return or modify graph data (a decision is yes/no, not a data read or write).

Prerequisites

• One or more ACTIVE KBAC policies whose subject.type / actions / resource.type cover the triple. If none exist, author them first with indykite-authzen-kbac; a decision with no matching policy is simply false.
• An AppAgent and its credentials token (the X-IK-ClientKey value).
• The IKG populated with the subject and resource nodes (and any relationships the condition matches). Evaluation reads the graph; it does not seed it.
• Every partial parameter the matched policy references, ready to pass under context.input_params.

If a prerequisite is missing, say so - fixing it first is far cheaper than debugging an opaque false decision.

Steps

1. Frame the triple and its context

Pin the three parts of the question, plus any per-request values:

Part	Field	Example
subject	subject.type + subject.id	Person / ada
action	action.name	PROVISION
resource	resource.type + resource.id	Server / gpu-node-7
context	context.input_params	{ "max_price": 120000 }

subject.id / resource.id are the nodes' external_ids; action.name is case-sensitive.

2. Build the request body

{
  "subject":  { "type": "Person", "id": "ada" },
  "resource": { "type": "Server",    "id": "gpu-node-7"  },
  "action":   { "name": "PROVISION" },
  "context":  { "input_params": { "max_price": 120000 } }
}

Supply context.input_params only when the matched policy's condition references a $name partial parameter; write each key without the leading $, keeping its type (numbers stay numbers). A ready body: assets/evaluation-provision-server.json.

3. Send the decision request

POST <API_URL>/access/v1/evaluation

Authentication:

• Always: X-IK-ClientKey: <AppAgent-credentials-token> - authenticates the calling application.
• Optional: Authorization: Bearer <user-access-token> - applies only in some cases (e.g. a condition references a token claim/scope); not required otherwise.

A runnable shell helper: scripts/evaluate.sh — run with --print to preview the curl (host-pinned; tokens redacted).

4. Read the decision

{ "decision": true }

true means at least one ACTIVE policy granted the (subject, action, resource) triple with its condition satisfied. false means no policy granted it - either no policy matched the triple, or the matching policy's condition did not hold for the supplied input_params and graph data. A false decision is a normal 200, not an error.

5. Verify

If the decision is not what you expected, walk this checklist before changing anything:

1. Policy ACTIVE? A draft/inactive policy is ignored.
2. Triple matches? subject.type, action.name, and resource.type must match the policy's subject.type, actions, and resource.type exactly (case-sensitive verbs).
3. Variables named subject / resource? The condition binds the request's subject/resource only through those reserved names.
4. IDs are external_ids? subject.id / resource.id are matched against node external_id. A wrong id silently matches nothing → false.
5. Every $param supplied? A missing input_params key the condition needs yields a 422 (errors: ["missing or wrong input params, '<name>'"]), not a silent false.
6. Data actually in the IKG? Confirm the subject node, resource node, and any matched relationship exist.

Full request/response schema, error table, and a deeper troubleshooting walk-through: references/evaluation-reference.md and references/troubleshooting.md.

Outcome

When this skill has been applied successfully:

• POST /access/v1/evaluation returns {"decision": true} for an allowed (subject, action, resource) triple with valid input_params, and {"decision": false} for a denied one.
• A missing required input_params key is surfaced as a 422 and corrected, not mistaken for a denial.
• The same triple can be fanned out through indykite-authzen-evaluations or invoked through the indykite-mcp-server authzen_evaluate tool with identical decision semantics.

Files in this skill

• references/evaluation-reference.md - the /evaluation endpoint: base path, auth, request/response shape, error codes, and pointers to the batch and search sibling skills.
• references/troubleshooting.md - why a decision is unexpectedly true/false and how to isolate the responsible policy.
• assets/evaluation-provision-server.json - runnable single-evaluation request body for the Person PROVISION Server example.
• scripts/evaluate.sh - Bash helper that posts a decision request to /access/v1/evaluation (host-pinned; --print to preview).

Agent-specific notes

This skill uses generic markdown instructions and works across all agents listed in the README. The agent needs to be able to issue HTTP requests (curl, an HTTP client, or the IndyKite Terraform provider). No Claude Code hooks, Cursor @-mentions, or Copilot workspace context are required.

References

• AuthZEN guide (developer hub)
• Dynamic authorization with Knowledge Graphs (developer hub)
• KBAC: Relationship-Based Authorization with the AuthZEN API
• KBAC: Parameterized Authorization with Input Params (max_price)
• Music dataset tutorial (worked KBAC + AuthZEN example)
• Credentials guide