indykite-authzen-search-action

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:

Endpoint	Pinned	Enumerates	Skill
/search/action	subject + resource	actions	this skill
/search/resource	subject + action	resources	indykite-authzen-search-resource
/search/subject	resource + action	subjects	indykite-authzen-search-subject

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

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-policies; search over an empty policy set returns {"results": []}.
• An AppAgent with credentials configured for the calling application (Credentials guide).
• 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:

Part	Field	Example
subject	subject.type + subject.id	Person / linus
resource	resource.type + resource.id	Server / gpu-node-7

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 location-routed 3.0-kbac policy on a composite IKG takes its logical location here too ({ "region": "east" }, a key of the project's alias_mapping); a missing or unknown location is a 422, and a user token for a different identity than subject is a 403 - see references/search-action-reference.md. A ready body: assets/search-action-request.json.

3. Send the search

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

The endpoint authenticates the calling application (its AppAgent credentials - always required) and optionally the user (an access token - applies only in some cases; when supplied it can narrow the results). Which credential goes in which request header is covered by the Credentials guide.

A runnable shell helper builds the authenticated request: 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 supplied user 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-policies.

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