IndyKite AuthZEN - action search

Action search asks the AuthZEN endpoint: which actions may this subject perform on this resource? It returns the list of granted action names under the project's currently ACTIVE KBAC policies and current graph state - not a single boolean.

It is one of three AuthZEN search endpoints, each pinning two of the three (subject, action, resource) parts and enumerating the third:

This skill covers building and sending the request and reading the results. It does not author policies - the 2.0-kbac policies whose actions these results come from are authored with indykite-authzen-kbac.

When to use

Activate this skill when the user wants to:

• list every action a subject may perform on a specific resource (e.g. "what can linus do with gpu-node-7?");
• drive a UI that shows only the operations a user is currently permitted on an item;
• debug why an expected action is or is not granted for a (subject, resource) pair.

Do not activate this skill for a single yes/no decision (indykite-authzen-evaluation), to enumerate resources or subjects instead (the sibling search skills), to run many decisions at once (indykite-authzen-evaluations), or to author a policy or read/write graph data (search only lists actions).

Prerequisites

• One or more ACTIVE KBAC policies whose subject.type / resource.type match the pair you are asking about. If none exist, author them first with indykite-authzen-kbac; search over an empty policy set returns {"results": []}.
• An AppAgent and its credentials token (the X-IK-ClientKey value).
• The IKG populated with the subject and resource nodes (and any relationships the policy conditions match). Search evaluates the graph; it does not seed it.
• Any partial parameters a candidate policy references, ready to pass under context.input_params.

If a prerequisite is missing, say so - an empty result set from a missing policy or absent node looks identical to a real "nothing permitted".

Steps

1. Pin the subject and the resource

Action search fixes both the subject and the resource and asks what is allowed between them. Identify each by its node external_id:

There is no action field - discovering the actions is the point.

2. Build the request body

{
  "subject":  { "type": "Person", "id": "linus" },
  "resource": { "type": "Server",    "id": "gpu-node-7" },
  "context":  { "input_params": { "max_price": 120000 } }
}

Include context.input_params only if a candidate policy's condition references a $name partial parameter; supply each key without the leading $, with the correct type (numbers stay numbers). A ready body: assets/search-action-request.json.

3. Send the search

POST <API_URL>/access/v1/search/action

Authentication:

• Always: X-IK-ClientKey: <AppAgent-credentials-token>.
• Optional: Authorization: Bearer <user-access-token> - applies only in some cases; when supplied it can narrow the results.

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

4. Read the results

{ "results": [ { "name": "DEPLOY" }, { "name": "REBOOT" }, { "name": "SNAPSHOT" } ] }

Each results[] entry is an action the subject may currently perform on that resource. An empty results array is a normal 200 meaning nothing is granted - not an error.

5. Verify

Empty or surprising results usually trace to: the policy isn't ACTIVE/matching, subject.id/resource.id aren't the nodes' external_ids, a required $param is missing or mistyped, the graph data is absent, or a Bearer token narrowed claim-gated actions. Full checklist: references/search-action-reference.md.

Outcome

When this skill has been applied successfully:

• POST /access/v1/search/action returns a results array of the actions a subject may perform on a specific resource under current ACTIVE policies and graph state (an empty array means nothing permitted — a normal 200).
• The actions returned line up with the actions of the KBAC policies authored via indykite-authzen-kbac.

Files in this skill

• references/search-action-reference.md - endpoint, auth, request/response shape, error codes, troubleshooting, sibling endpoints.
• assets/search-action-request.json - runnable action-search request body for the linus / gpu-node-7 example.
• scripts/search-action.sh - Bash helper that posts a search request to /access/v1/search/action (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)
• Config API documentation - authorization policies
• Credentials guide