KBAC: Batch Authorization with Multiple Evaluations (Boxcarring)

This example demonstrates batch authorization using the authZEN Access Evaluations API:

What is boxcarring?

Multiple authorization questions combined into a single API request, reducing network round-trips.

Example batch request:

- "Can knightrider drive kitt?"

- "Can knightrider drive cadillacv16?"

- "Can karel ride harmonika?"

- "Can karel drive harmonika?"

All answered in ONE API call.

API reference: https://openid.net/specs/authorization-api-1_0-03.html#name-access-evaluations-api

Request structure:

- Default subject/action can be set at the top level

- Each evaluation in the array can override defaults

- Response contains decision for each evaluation in order

Policy version note: the policies in this example use "policy_version": "2.0-kbac". The same policy JSON is also accepted with "policy_version": "3.0-kbac" (identical schema, raw-Cypher semantics; do not reference $subject_id or external properties). Only 3.0-kbac additionally accepts USE graph.byName() routing and CALL { } subqueries for composite / data-residency IKGs - see resources authz-7 and authz-8.

Use case

Scenario: A transportation app needs to check multiple permissions when a user opens the app.

Graph (same dataset as authz-1):

- knightrider -[DRIVES]-> kitt, satchmo -[DRIVES]-> cadillacv16, alice -[DRIVES]-> cadillacv16

- karel -[HAS]-> listek (Ticket) -[FOR]-> harmonika (Bus)

Policies defined:

1. CAN_DRIVE policy: Person can drive a Car if a DRIVES relationship exists

2. CAN_RIDE policy: Person can ride a Bus if the Person HAS a Ticket FOR that Bus

Single batch request checks (default subject karel, default action CAN_DRIVE):

- Can knightrider drive kitt? (CAN_DRIVE policy)

- Can knightrider drive cadillacv16? (CAN_DRIVE policy)

- Can karel ride harmonika? (CAN_RIDE policy)

- Can karel drive harmonika? (no policy grants CAN_DRIVE on a Bus)

Response (in order):

- {decision: true}

- {decision: false}

- {decision: true}

- {decision: false}

Performance benefit: 4 authorization decisions with 1 API call instead of 4.

Requirements

Prerequisites:

- ServiceAccount credentials: For creating policies (Bearer token)

- AppAgent credentials: For data ingestion and authorization queries (X-IK-ClientKey)

Required API access:

- POST /capture/v1/nodes/ and /capture/v1/relationships/ (graph data)

- POST /configs/v1/authorization-policies (create policies - called twice)

- POST /access/v1/evaluations (batch evaluation endpoint - note plural)

Steps

Step 1: Ingest Graph Data

- Authentication: AppAgent credential (X-IK-ClientKey header)

- Action: POST nodes (Person: alice, knightrider, satchmo, karel; Car: kitt, cadillacv16; Bus: harmonika; Ticket: listek; Laptop: airbook-xyz) and relationships (DRIVES, OWNS, HAS, FOR)

- Result: Graph ready for authorization queries

Step 2: Create Multiple KBAC Policies

- Authentication: ServiceAccount credential (Bearer token)

- Action: POST CAN_DRIVE policy (Person -[DRIVES]-> Car)

- Action: POST CAN_RIDE policy (Person -[HAS]-> Ticket -[FOR]-> Bus)

- Result: Two policy IDs returned

Step 3: Run Batch Evaluation

- Authentication: AppAgent credential (X-IK-ClientKey header)

- Action: POST to /access/v1/evaluations (plural) with an array of checks

- Request: top-level subject Person karel and action CAN_DRIVE are the defaults; each entry overrides what it needs:

1. subject knightrider, resource Car kitt (default action CAN_DRIVE)

2. subject knightrider, resource Car cadillacv16 (default action CAN_DRIVE)

3. resource Bus harmonika, action CAN_RIDE (default subject karel)

4. resource Bus harmonika (default subject karel, default action CAN_DRIVE)

- Result: Array of decisions in the same order

Step 5: Cleanup

- Action: DELETE both policy configurations

Step 1

Capture the nodes needed for this use case.

POST https://eu.api.indykite.com/capture/v1/nodes/Json

{
  "nodes": [
    {
      "external_id": "alice",
      "is_identity": true,
      "type": "Person",
      "properties": [
        {
          "type": "email",
          "value": "alice@email.com"
        },
        {
          "type": "given_name",
          "value": "Alice"
        },
        {
          "type": "last_name",
          "value": "Smith"
        }
      ]
    },
    {
      "external_id": "knightrider",
      "type": "Person",
      "is_identity": true,
      "properties": [
        {
          "type": "email",
          "value": "knightrider@demo.com"
        },
        {
          "type": "name",
          "value": "Michael Knight"
        }
      ]
    },
    {
      "external_id": "satchmo",
      "type": "Person",
      "is_identity": true,
      "properties": [
        {
          "type": "email",
          "value": "satchmo@demo.com"
        },
        {
          "type": "name",
          "value": "Louis Armstrong"
        }
      ]
    },
    {
      "external_id": "karel",
      "type": "Person",
      "is_identity": true,
      "properties": [
        {
          "type": "email",
          "value": "karel@demo.com"
        },
        {
          "type": "name",
          "value": "Karel Plihal"
        }
      ]
    },
    {
      "external_id": "kitt",
      "type": "Car",
      "is_identity": false,
      "properties": [
        {
          "type": "manufacturer",
          "value": "pontiac"
        },
        {
          "type": "model",
          "value": "Firebird"
        }
      ]
    },
    {
      "external_id": "cadillacv16",
      "type": "Car",
      "is_identity": false,
      "properties": [
        {
          "type": "manufacturer",
          "value": "Cadillac"
        },
        {
          "type": "model",
          "value": "V-16"
        }
      ]
    },
    {
      "external_id": "harmonika",
      "type": "Bus",
      "is_identity": false,
      "properties": [
        {
          "type": "manufacturer",
          "value": "Ikarus"
        },
        {
          "type": "model",
          "value": "280"
        }
      ]
    },
    {
      "external_id": "listek",
      "type": "Ticket",
      "is_identity": false
    },
    {
      "external_id": "airbook-xyz",
      "type": "Laptop",
      "is_identity": false
    }
  ]
}

Capture the relationships needed for this use case.

POST https://eu.api.indykite.com/capture/v1/relationships/Json

{
  "relationships": [
    {
      "source": {
        "external_id": "knightrider",
        "type": "Person"
      },
      "target": {
        "external_id": "kitt",
        "type": "Car"
      },
      "type": "DRIVES"
    },
    {
      "source": {
        "external_id": "satchmo",
        "type": "Person"
      },
      "target": {
        "external_id": "cadillacv16",
        "type": "Car"
      },
      "type": "DRIVES"
    },
    {
      "source": {
        "external_id": "karel",
        "type": "Person"
      },
      "target": {
        "external_id": "listek",
        "type": "Ticket"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "listek",
        "type": "Ticket"
      },
      "target": {
        "external_id": "harmonika",
        "type": "Bus"
      },
      "type": "FOR"
    },
    {
      "source": {
        "external_id": "karel",
        "type": "Person"
      },
      "target": {
        "external_id": "airbook-xyz",
        "type": "Laptop"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "alice",
        "type": "Person"
      },
      "target": {
        "external_id": "airbook-xyz",
        "type": "Laptop"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "knightrider",
        "type": "Person"
      },
      "target": {
        "external_id": "kitt",
        "type": "Car"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "alice",
        "type": "Person"
      },
      "target": {
        "external_id": "cadillacv16",
        "type": "Car"
      },
      "type": "DRIVES"
    }
  ]
}

Step 2

KBAC Policy which rules that a Person node can drive a car if the Person node has a relation DRIVES with a car in json format.

policy.jsonJson

{
  "meta": {
    "policy_version": "2.0-kbac"
  },
  "subject": {
    "type": "Person"
  },
  "actions": [
    "CAN_DRIVE"
  ],
  "resource": {
    "type": "Car"
  },
  "condition": {
    "cypher": "MATCH (subject:Person)-[:DRIVES]->(resource:Car)"
  }
}

Request to create the KBAC Policy configuration using REST.

POST https://eu.api.indykite.com/configs/v1/authorization-policiesJson

{
  "project_id": "your_project_gid",
  "description": "description of policy",
  "display_name": "policy name",
  "name": "policy-name",
  "policy": "{\"meta\":{\"policy_version\":\"2.0-kbac\"},\"subject\":{\"type\":\"Person\"},\"actions\":[\"CAN_DRIVE\"],\"resource\":{\"type\":\"Car\"},\"condition\":{\"cypher\":\"MATCH (subject:Person)-[:DRIVES]->(resource:Car)\"}}",
  "status": "ACTIVE",
  "tags": []
}

Request to create the KBAC Policy configuration using Python.

policy_request.pyPython


import http.client

conn = http.client.HTTPSConnection("eu.api.indykite.com")

payload = "{"description": "",
  "display_name": "",
  "name": "",
  "policy": "",
  "project_id": "",
  "status": "ACTIVE",
  "tags": [
    ""
  ]}"
headers = {
    'Content-Type': "application/json",
    'Authorization': "YOUR_SECRET_TOKEN"
}

conn.request("POST", "/configs/v1/authorization-policies", payload, headers)
res = conn.getresponse()
data = res.read()

Request to read the KBAC Policy configuration using REST

GET https://eu.api.indykite.com/configs/v1/authorization-policies/{id}Json

{
  "id": "your_policy_configuration_gid"
}

Request to read the KBAC Policy configuration using Python.

policy_request.pyPython


import http.client

conn = http.client.HTTPSConnection("eu.api.indykite.com")
headers = { 'Authorization': "YOUR_SECRET_TOKEN" }
conn.request("GET", "/configs/v1/authorization-policies/{{id}}", headers=headers)
res = conn.getresponse()
data = res.read()

KBAC Policy which rules that a Person node can ride a bus if the Person node has a ticket for the bus in json format.

policy.jsonJson

{
  "meta": {
    "policy_version": "2.0-kbac"
  },
  "subject": {
    "type": "Person"
  },
  "actions": [
    "CAN_RIDE"
  ],
  "resource": {
    "type": "Bus"
  },
  "condition": {
    "cypher": "MATCH (subject)-[:HAS]->(ticket:Ticket)-[:FOR]->(resource)"
  }
}

Request to create the KBAC Policy configuration using REST.

POST https://eu.api.indykite.com/configs/v1/authorization-policiesJson

{
  "project_id": "your_project_gid",
  "description": "description of policy",
  "display_name": "policy name",
  "name": "policy-name",
  "policy": "{\"meta\":{\"policy_version\":\"2.0-kbac\"},\"subject\":{\"type\":\"Person\"},\"actions\":[\"CAN_RIDE\"],\"resource\":{\"type\":\"Bus\"},\"condition\":{\"cypher\":\"MATCH (subject)-[:HAS]->(ticket:Ticket)-[:FOR]->(resource)\"}}",
  "status": "ACTIVE",
  "tags": []
}

Request to create the KBAC Policy configuration using Python.

policy_request.pyPython


import http.client

conn = http.client.HTTPSConnection("eu.api.indykite.com")

payload = "{"description": "",
  "display_name": "",
  "name": "",
  "policy": "",
  "project_id": "",
  "status": "ACTIVE",
  "tags": [
    ""
  ]}"
headers = {
    'Content-Type': "application/json",
    'Authorization': "YOUR_SECRET_TOKEN"
}

conn.request("POST", "/configs/v1/authorization-policies", payload, headers)
res = conn.getresponse()
data = res.read()

Request to read the KBAC Policy configuration using REST.

GET https://eu.api.indykite.com/configs/v1/authorization-policies/{id}Json

{
  "id": "your_policy_configuration_gid"
}

Request to read the KBAC Policy configuration using Python.

policy_request.pyPython


import http.client

conn = http.client.HTTPSConnection("eu.api.indykite.com")
headers = { 'Authorization': "YOUR_SECRET_TOKEN" }
conn.request("GET", "/configs/v1/authorization-policies/{{id}}", headers=headers)
res = conn.getresponse()
data = res.read()

Step 3

Json to run KBAC access multi-evaluations.

The elements outside evaluations are the default values.

Here we have a default value for subject and for action.

If a top-level key is designated in the evaluations array then the value of that will take precedence over the default value.

POST https://eu.api.indykite.com/access/v1/evaluationsJson

{
  "subject": {
    "type": "Person",
    "id": "karel"
  },
  "action": {
    "name": "CAN_DRIVE"
  },
  "evaluations": [
    {
      "subject": {
        "type": "Person",
        "id": "knightrider"
      },
      "resource": {
        "type": "Car",
        "id": "kitt"
      }
    },
    {
      "subject": {
        "type": "Person",
        "id": "knightrider"
      },
      "resource": {
        "type": "Car",
        "id": "cadillacv16"
      }
    },
    {
      "resource": {
        "type": "Bus",
        "id": "harmonika"
      },
      "action": {
        "name": "CAN_RIDE"
      }
    },
    {
      "resource": {
        "type": "Bus",
        "id": "harmonika"
      }
    }
  ]
}

Response to the KBAC Evaluations endpoint request.

Response 200Json

{
  "evaluations": [
    {
      "decision": true
    },
    {
      "decision": false
    },
    {
      "decision": true
    },
    {
      "decision": false
    }
  ]
}

Request to run the KBAC Evaluations endpoint.

evaluations.pyPython


import http.client

conn = http.client.HTTPSConnection("eu.api.indykite.com")

payload = "{
    "subject": {"type": "Person",
        "id": "karel"}, 
    "action": {"name": "CAN_DRIVE"},
    "evaluations": [
        {
          	"subject": {"type": "Person",
                "id": "knightrider"}, 
            "resource": {"type": "Car",
                "id": "kitt"}
        },
        {
          	"subject": {"type": "Person",
                "id": "knightrider"}, 
            "resource": {"type": "Car",
                "id": "cadillacv16"}
        },
        {
          	"resource": {"type": "Bus",
                "id": "harmonika"},
            "action": {"name": "CAN_RIDE"}
        },
        {
          	"resource": {"type": "Bus",
                "id": "harmonika"}
        }
    ]
}"

headers = {
    'Content-Type': "application/json",
    'X-IK-ClientKey': ""
}

conn.request("POST", "/access/v1/evaluations", payload, headers)

res = conn.getresponse()
data = res.read()

Step 5

Delete the KBAC Policies.

DELETE https://eu.api.indykite.com/configs/v1/authorization-policies/{id}Json

{
  "id": "your_policy_configuration_gid"
}

Request to delete the KBAC Policies.

del.pyPython


import http.client

conn = http.client.HTTPSConnection("eu.api.indykite.com")

headers = { 'Authorization': "Bearer ...", 'Content-Type': "application/json" }

conn.request("DELETE", "/configs/v1/authorization-policies/{id}", headers=headers)

res = conn.getresponse()
data = res.read()

API Endpoints

/capture/v1/nodes

/capture/v1/relationships

/configs/v1/authorization-policies

/access/v1/evaluations

View OpenAPI docs

Related Guides

Authzen Dynamic Authz Sandbox

Related Resources

KBAC: List the Active Authorization Policies of a Project with GET /access/v1/policies

KBACPython

KBAC: Batch Authorization with Multiple Evaluations (Boxcarring)

KBAC: Batch Authorization with Multiple Evaluations (Boxcarring)

Use case

Requirements

Steps

Step 1

Step 2

Step 3

Step 5

API Endpoints

Related Guides

Tags

Related Resources

KBAC: Relationship-Based Authorization with authZEN API

KBAC: Step-Up Authentication Advice in Authorization Responses

KBAC: Parameterized Authorization with Input Params (max_price)

KBAC: Check a Permission Grid for One Subject with authZEN Evaluations (Boxcar)

KBAC: Token-Scope-Gated Read/Write Permissions

KBAC 3.0: Raw-Cypher Policies with CALL { } Subqueries and USE Routing

KBAC 3.0: Data Residency - Location-Routed AuthZEN Decisions

KBAC: List the Active Authorization Policies of a Project with GET /access/v1/policies