Evaluate an action

Use this operation at a trusted enforcement boundary before performing a real side effect. It creates one authoritative decision and returns the policy effect your integration must enforce.

POST/workspaces/{workspace_slug}/evaluate

Configuration and parameters

Use ACTERA_BASE_URL, ACTERA_WORKSPACE_SLUG, and authentication headers supplied by your server configuration.

Parameter	Location	Required	Description
workspace_slug	Path	Yes	Workspace selected by the trusted integration.

Request fields

Field	Required	Description
idempotency_key	Yes	Stable key for this logical action.
agent.id	Yes	Configured agent identity.
action.type	Yes	Stable operation name used for applicability.
action.attributes	No	Domain values required by policy.
context	No	Additional immutable facts required by policy.
intended_call	No	Call envelope for supported managed-resume integrations.

Request

curl --request POST "$ACTERA_BASE_URL/workspaces/$ACTERA_WORKSPACE_SLUG/evaluate" \
  --header 'Content-Type: application/json' \
  "${ACTERA_AUTH_HEADERS[@]}" \
  --data '{
    "idempotency_key": "refund-request-01842",
    "agent": { "id": "refund-agent" },
    "action": { "type": "refund.create", "attributes": { "amount": 80, "currency": "GBP" } },
    "context": { "customer": { "previous_refunds": 0, "fraud_flagged": false } }
  }'

const decision = await actera.authorizeAction({
  agent: { id: 'refund-agent' },
  action: { type: 'refund.create', attributes: { amount: 80, currency: 'GBP' } },
  context: { customer: { previous_refunds: 0, fraud_flagged: false } },
  idempotencyKey: 'refund-request-01842',
})

if (decision.effect === 'ALLOW') await performAction()
else if (decision.effect === 'REQUIRE_APPROVAL') await pauseForApproval(decision.id)
else throw new Error(decision.explanation || 'Actera blocked the action')

Response excerpt

{
  "id": "dec_7f26",
  "agent_id": "refund-agent",
  "action_type": "refund.create",
  "effect": "ALLOW",
  "status": "ALLOWED",
  "policy_bundle_version": "12",
  "matched_policy_ids": ["pol_refund_small"],
  "matched_rules": ["small-refund-allow"],
  "explanation": "Low-value refund is allowed",
  "version": "4"
}

The response contains additional evidence. Enforce effect, retain id, and retrieve the decision later.

Errors and retries

Missing required identity or idempotency fields returns 400. Reusing a key for different input returns 409. Retry temporary failures with the same key; never create a new key merely because a response was lost. See the TypeScript integration for the complete boundary pattern.