Agentbase Policy

AgentBase Policy Service

Author authorization policies for GreenNode AgentBase resources. A policy decides whether a given caller (identified by principal) is allowed to perform a given action on a given resource, optionally conditioned on attributes of the caller and the request context.

The Policy service is resource-type-agnostic by design — resources are written as <type>:<name> and actions are free-form strings. Today the only resource type wired into a runtime enforcement point is gateway (the Resource Gateway, which evaluates MCP JSON-RPC calls such as tools/call), but the model is intended to extend to additional resource types over time.

Parse the user's arguments to determine the operation and optional group/policy ID.

Base URLs

• Policy: https://agentbase.api.vngcloud.vn/policy/api/v1
• Operator catalog: https://agentbase.api.vngcloud.vn/policy/api/v1/policies/condition-operators

Authentication & Endpoints

Read the shared auth setup reference at /agentbase skill's references/auth-setup.md for full IAM credential configuration. In brief: run bash .claude/skills/agentbase/scripts/check_credentials.sh iam to verify credentials are configured, then use TOKEN=$(bash .claude/skills/agentbase/scripts/get_token.sh) to obtain a token. NEVER read .greennode.json or .env directly — always use the helper scripts. On 401: re-run with --force. If check_credentials.sh iam returns MISSING, STOP — you MUST read the "If Credentials Are Not Found" section in /agentbase skill's references/auth-setup.md and follow it exactly. Do NOT skip this or provide your own credential setup instructions.

IMPORTANT: Before constructing any API URL, read /agentbase skill's references/endpoints.md for the domain validation whitelist. Only use domains listed there.

Interaction Guidelines

• Never assume API response structure — always inspect the actual response before extracting fields. Do not guess field names.
• Guide first, act only when asked — if the user asks "how to" author a policy or what an operator means, respond with explanation only. Do NOT execute API calls unless they explicitly ask you to do it for them.
• Confirm before executing (HARD GATE) — before any action (create, update, delete), present a clear summary of the operation, the full statement JSON (effect / principal / actions / resources / condition), and the target Policy Group, then ask the user to confirm. Do NOT auto-execute. Proceed only when the user responds with an explicit confirmation keyword: yes, confirm, ok, approve, proceed, go ahead, do it, ship it, lgtm, or equivalent affirmative. If the user responds with anything else (parameter changes, questions, corrections), treat it as adjustment input — update the plan and re-present for confirmation. NEVER interpret a non-confirmation response as approval. For destructive operations (delete policy, delete policy group — which cascades and removes all child policies), additionally warn that the action is irreversible.
• Never auto-decide policy fields — when authoring a policy, always ask the user for effect, principal, actions, resources, and each condition clause. You may recommend sensible defaults and show the impact of each choice, but never silently pick.
• Deny-wins reminder — when any deny policy in a group matches a request, the decision is deny. If a user writes a deny rule alongside allow rules in the same group, surface this so they understand the outcome.
• Resource-type-specific bypasses — some resource types short-circuit certain actions regardless of policy. For gateway today, the Resource Gateway always permits the MCP discovery method tools/list. If a user expects to block a "list/discovery"-style action with a policy, check the resource type's behaviour first and say so.
• Dry-run support: when user requests --dry-run or preview, show the exact API request (method, URL, headers, payload) and explain the expected outcome WITHOUT executing.
• Always read full API response body — capture the JSON response (not just status). On 400 the server returns a precise error such as operator "is" is not supported; see GET /api/v1/policy/condition-operators — surface that text to the user verbatim instead of paraphrasing.

Core Concepts

Resource-type-specific behaviour. Each resource type can short-circuit certain actions. For gateway today, tools/list is always allowed regardless of policies. New resource types may have their own bypasses — when in doubt, check the resource type's documentation.

Supported Condition Operators (the only nine)

Any other operator name is rejected by the API (HTTP 400) with a pointer to the operator catalog. Live source of truth: GET /policy/api/v1/policies/condition-operators.

Condition Keys

Each key is <prefix>.<identifier> (single identifier, letters/digits/underscore, not starting with a digit; no nested paths). The API accepts three prefixes at create/update time — context.<name>, context.input.<name>, principal.<name> — but only the specific keys below are populated by the enforcement point today. Any other key in those namespaces is syntactically valid but will never match at decision time, so the rule effectively never fires.

For the gateway resource type, the keys populated today are:

principal.id is reserved (caller identity belongs in the policy's principal field, not in a condition) and resource.* keys are not supported.

Operations Summary

Policy Groups

Policies (nested under a group)

Operator catalog

Pagination: Policy service uses 1-indexed pagination with the GreenNode-style response shape (listData, totalItem, totalPage, page, pageSize). Defaults: page=1, page_size=10, max page_size=100.

Read references/policy-statement.md for full statement authoring rules. Read references/policy-ops.md for curl recipes for every endpoint. Read references/examples.md for end-to-end realistic policy examples.

Top-Level Instructions

1. Parse the user's argument to determine the operation (group or policy, plus create | list | get | update | delete) and any name/ID provided.
2. If credentials are not configured, follow the credential setup flow in /agentbase skill's references/auth-setup.md — do not invent your own.
3. Before building a request, confirm the Policy Group ID the policy belongs to. If unknown, list groups first (GET /policy-groups) and let the user pick.
4. For create / update: collect each statement field individually — effect, principal, actions, resources, and each condition clause. Validate locally against the rules in references/policy-statement.md before sending; this surfaces problems faster than a round trip.
5. For delete policy group: warn that deletion cascades to all child policies and is irreversible.
6. After any create / update / delete, fetch the affected resource(s) again so the user sees the persisted state, not your assumption.
7. Show curl examples by default (this skill is for platform management, not in-agent code). If the user is scripting from Python, use requests with the same payload shape.

Troubleshooting