indykite-authzen-kbac

IndyKite KBAC - authorization policies

KBAC (Knowledge-Based Access Control) is IndyKite's graph-driven authorization model. A KBAC policy declares who (subject) may perform which operations (actions) on what (resource), gated by a condition in Cypher (the Neo4j / openCypher graph query language) evaluated against the IKG — IndyKite's knowledge graph, a property-graph database. The policy itself renders no decision - it is the rule that the AuthZEN endpoints consult when a decision or search is requested.

This skill is the home of the KBAC policy lifecycle: writing the policy JSON and managing it through the Config API.

• A policy with meta.policy_version: "2.0-kbac", a single subject.type, an actions list, a single resource.type, and a condition.cypher that binds the reserved variables subject and resource.
• The Config API operations on /configs/v1/authorization-policies: create (POST), read (GET /{id} or by name), list (GET ?project_id=…&type=kbac), update (PUT /{id} with an If-Match ETag), and delete (DELETE /{id}).
• Publishing: a policy must be ACTIVE to participate in decisions; an INACTIVE or DRAFT policy is stored but ignored (DRAFT may even be invalid).

Once a policy is ACTIVE, the runtime AuthZEN skills evaluate it:

Need	Endpoint	Skill
One yes/no decision	/access/v1/evaluation	indykite-authzen-evaluation
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

When to use

Activate this skill when the user wants to:

• author a KBAC authorization policy (policy_version: 2.0-kbac, subject, actions, resource, condition.cypher);
• create / publish a policy through the Config API, or flip it between DRAFT and ACTIVE;
• read, list, update, or delete existing KBAC policies (including listing with ?type=kbac to separate them from CIQ policies);
• needs the policy that backs an indykite-authzen-evaluation decision or the indykite-mcp-server authzen_evaluate tool.

Do not activate this skill when the user wants to:

• make a decision (one triple or many) - use indykite-authzen-evaluation / indykite-authzen-evaluations;
• enumerate allowed actions, resources, or subjects - use the search skills -search-action / -search-resource / -search-subject;
• author a ContX IQ read/write policy (the same /configs/v1/authorization-policies endpoint also serves CIQ, distinguished by type=ciq) - use the indykite-ciq-* skills;
• create / update / delete graph data - a KBAC policy is a rule over the graph, not a write to it.

Prerequisites

• An IndyKite project, and the project's GID in PROJECT_GID - it becomes the policy's project_id.
• A Service Account token with Config API write access, in SERVICE_ACCOUNT_TOKEN - used for every /configs/v1/authorization-policies call.
• A subject type for the policy - the node type making the request (Person, Service, Namespace, etc.). A policy is restricted to a single subject type; if two subject types need the same action, write two policies.
• The IKG model the condition will match (node types, properties, relationships). The policy can be authored before the data exists, but a decision over an empty graph is just false.

If any of these are missing, say so before writing JSON.

Steps

1. Frame the rule as (subject, actions, resource, condition)

Every KBAC policy answers one shape of question. Pin down all four parts before writing JSON:

Part	What it is	Example
subject	The single node type making the request.	Person
actions	One or more uppercase verbs the policy grants.	["PROVISION"]
resource	The single node type being acted on.	Server
condition	A Cypher pattern + WHERE that must hold for a decision to be true.	price within budget

Working example used throughout this skill:

A Person (subject) may PROVISION a Server (resource) when the server's price is within a budget supplied at evaluation time.

2. Write the Cypher condition

The condition is a single cypher string. Two hard rules:

• It must bind a variable literally named subject (matching subject.type) and a variable literally named resource (matching resource.type). At decision time the AuthZEN request's subject.id / resource.id are matched against each node's external_id.
• Anything that varies per request is a partial parameter written $name in the WHERE clause; the decision call supplies it under context.input_params (without the $). Here the budget is $max_price.

MATCH (subject:Person), (resource:Server)
WHERE resource.property.price <= $max_price

For relationship-based rules, match the relationship instead of (or in addition to) a property check:

MATCH (subject:Person)-[:CAN_AFFORD]->(resource:Server)

For the full condition grammar (attribute references, multi-hop patterns, partial parameters) see references/policy-reference.md.

3. Assemble the policy and its create envelope

A KBAC policy has exactly these top-level keys: meta.policy_version ("2.0-kbac"), subject.type, actions, resource.type, and condition.cypher.

The Config API does not take the policy object directly - it takes a create envelope in which the policy is a stringified JSON value:

{
  "name": "kbac-person-provision-server",
  "display_name": "Person: PROVISION a Server within budget",
  "description": "Allow a Person to PROVISION a Server when its price is within a budget supplied at evaluation time.",
  "project_id": "<project-gid>",
  "policy": "{ \"meta\": { \"policy_version\": \"2.0-kbac\" }, … }",
  "status": "ACTIVE"
}

For readability the asset assets/policy-provision-server.json keeps policy as an object and project_id as a placeholder; the create step sets project_id and stringifies policy just before sending.

4. Create the policy

POST <API_URL>/configs/v1/authorization-policies

Authenticate with the Service Account token: Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>.

# set project_id and stringify only the `policy` field, then POST
jq --arg pid "$PROJECT_GID" '.project_id = $pid | .policy |= tojson' assets/policy-provision-server.json \
  | curl -X POST "$API_URL/configs/v1/authorization-policies" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN" \
      -d @-

Or use the helper scripts/create-policy.sh, which sets project_id, stringifies the policy field, pins the IndyKite host, and redacts the token under --print.

A 201 Created returns the policy's id (a gid:…), audit fields (create_time, created_by, …), and an ETag header. Keep the id and ETag - update and delete need them. The policy participates in decisions only when its status is ACTIVE.

5. Read, list, update, and delete

The same /configs/v1/authorization-policies path manages the policy lifecycle (all with the Service Account token):

• Read by id: GET /configs/v1/authorization-policies/{id} - returns the full record, including the stringified policy, status, tags, audit fields, and the current ETag.
• Read by name: GET /configs/v1/authorization-policies/{name}?location={PROJECT_GID}.
• List KBAC policies: GET /configs/v1/authorization-policies?project_id={PROJECT_GID}&type=kbac - type=kbac returns only KBAC policies (use type=ciq for ContX IQ). List responses carry an empty policy string per item; read by id to get the body.
• Update: PUT /configs/v1/authorization-policies/{id} with header If-Match: <etag> and a body of the fields to change (display_name, description, policy, status, tags). Use this to publish (status: "ACTIVE"), deactivate (status: "INACTIVE"), or hold as DRAFT, or to revise the condition. A new ETag comes back.
• Delete: DELETE /configs/v1/authorization-policies/{id} with header If-Match: <etag>.

Full request/response shapes, response fields, and the ETag concurrency rules are in references/policy-reference.md.

Outcome

When this skill has been applied successfully:

• A KBAC policy exists in the project with policy_version: "2.0-kbac", a single subject.type, an actions list, a single resource.type, and a condition.cypher binding subject and resource.
• The policy is ACTIVE (or deliberately INACTIVE / DRAFT), and its id and current ETag are known so it can be read, updated, or deleted.
• Listing with ?type=kbac shows the policy, and an indykite-authzen-evaluation decision over a matching (subject, action, resource) triple reflects it.

Files in this skill

• references/policy-reference.md - KBAC policy schema (meta, subject, actions, resource, condition.cypher, partial parameters, multi-action and relationship variants) and the Config API lifecycle (create / read / list ?type=kbac / update / delete, ETag concurrency, response fields).
• assets/policy-provision-server.json - runnable KBAC policy create envelope for the Person PROVISION Server example.
• scripts/create-policy.sh - Bash helper that sets project_id, stringifies policy, and POSTs the create envelope to /configs/v1/authorization-policies (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 - see References). No Claude Code hooks, Cursor @-mentions, or Copilot workspace context are required.

References

• AuthZEN guide (developer hub)
• Dynamic authorization with Knowledge Graphs (developer hub)
• Config API documentation - authorization policies
• Cypher query language manual (Neo4j; openCypher) - the graph query language used in KBAC policy conditions over the IndyKite Knowledge Graph.
• Music dataset tutorial (worked KBAC policy + AuthZEN example)
• KBAC recipes (developer hub resources)
• IndyKite Terraform provider - indykite_authorization_policy
• Credentials guide