Indykite Authzen Kbac Policies

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" (the default, platform-rewritten Cypher) or "3.0-kbac" (raw Cypher, usable on any IKG, with optional location routing for composite IKGs - see Location-aware policies), 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:

When to use

Activate this skill when the user wants to:

• author a KBAC authorization policy (policy_version 2.0-kbac or 3.0-kbac, subject, actions, resource, condition.cypher);
• author a location-aware policy for a composite / data-residency IKG (3.0-kbac with USE graph.byName() routing);
• 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.
• For a 2.0-kbac policy, the subject nodes must be identity nodes - ingested with is_identity: true (see indykite-capture-upsert-nodes). A subject ingested as a plain entity never matches a 2.0-kbac condition, so every decision quietly evaluates to false. 3.0-kbac matches the subject by type and external ID only and does not require is_identity.
• 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. For a populated IKG, the exact type and property spellings can be read from the Data Schema API (indykite-data-schema).

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:

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, and the reserved $subject_id parameter that 2.0-kbac binds to the user token's identity) see references/policy-reference.md.

3. Assemble the policy and its create envelope

A KBAC policy has exactly five top-level keys: meta (with meta.policy_version set to "2.0-kbac" or "3.0-kbac"), subject (with subject.type), actions, resource (with resource.type), and condition (required condition.cypher; optional condition.filter, a graph-free pre-check over token claims and input_params - see references/policy-reference.md).

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.

Location-aware policies for data residency (3.0-kbac)

On a composite IKG - one logical graph spanning multiple constituent databases so that individual nodes can be stored in a specific location (see the Data Residency guide) - a 2.0-kbac condition always evaluates against the default database, where located nodes exist only as lightweight proxies (external ID, type, and location - no property data). To evaluate a condition inside a location constituent, author the policy as 3.0-kbac:

• The condition is raw Cypher: it runs as authored; the platform only pins subject / resource by type and external ID and appends the projection.
• Route with USE graph.byName(...) - static (USE graph.byName('ikcomposite.db2') always evaluates in that constituent) or dynamic (USE graph.byName($region)), where $region becomes a location parameter: at decision time the caller passes a logical location (a key of the project's alias_mapping, e.g. "east") under context.input_params, and IndyKite translates it to the physical constituent just before execution. Callers never see or supply physical database names.
• CALL { } subqueries with inner RETURNs are allowed (each subquery can carry its own USE clause), so one condition can combine matches from several constituents. Both are rejected on 2.0-kbac.
• The subject does not need to be an identity node: it is matched by type and external ID. Instead, when the decision request carries a user (OAuth bearer) token, the token's subject must be the same identity as the request's subject, or the call is denied with bearer token subject differs from requested subject.
• Conditions referencing external (resolver-backed) properties are rejected at creation (external properties cannot be used in data-residency policies); they are supported only in 2.0-kbac conditions.

{
  "meta": { "policy_version": "3.0-kbac" },
  "subject": { "type": "Person" },
  "actions": ["CAN_DRIVE"],
  "resource": { "type": "Car" },
  "condition": {
    "cypher": "USE graph.byName($region) MATCH (subject:Person)-[:OWNS]->(resource:Car)"
  }
}

The lifecycle is unchanged - same endpoint, create envelope, statuses, and ETag rules as steps 3-5; only the policy JSON differs. Note that 3.0-kbac itself does not require a composite database - only USE routing (static or dynamic) does; a 3.0-kbac policy without a USE clause evaluates on any IKG as plain raw Cypher. Residency support is opt-in per policy: existing 2.0-kbac policies keep working, and a valid 2.0-kbac condition can be carried over by switching meta.policy_version (as long as it references neither $subject_id nor external properties, both of which 3.0-kbac rejects). The full 2.0 vs 3.0 comparison, authoring rules, and decision-time failure modes are in references/policy-reference.md; a runnable create envelope is in assets/policy-location-routed.json.

Outcome

When this skill has been applied successfully:

• A KBAC policy exists in the project with policy_version "2.0-kbac" (or "3.0-kbac" for location-aware conditions), 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, the optional condition.filter, partial parameters, multi-action and relationship variants), the 2.0 vs 3.0 version comparison with 3.0-kbac routing and authoring rules, 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.
• assets/policy-location-routed.json - runnable 3.0-kbac create envelope with dynamic USE graph.byName($region) location routing.
• 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)
• Data Residency guide (developer hub) - regions, composite databases, and 3.0-kbac location routing
• 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)
• KBAC 3.0: raw-Cypher policies with CALL { } subqueries and USE routing (authz-7)
• KBAC 3.0: location-routed policies for data residency (authz-8)
• IndyKite Terraform provider - indykite_authorization_policy
• Credentials guide