Skip to main content
AgentRein enforces a strict security boundary between automated agent clients and human operators.

​
1. Authentication Scopes

AgentRein separates authentication into two distinct categories:

​
Agent API Keys (ar_live_... / ar_test_...)

Agent API keys authenticate SDK client instances. Upon initialization, the SDK exchanges the API key for a short-lived Bearer token via POST /auth/token. API keys are restricted to an allow-list of SDK operational endpoints:
  • POST /sessions — Create session
  • GET /sessions/:id — Read session state
  • PATCH /sessions/:id — Complete session
  • POST /sessions/:id/rollback — Trigger session rollback
  • POST /sessions/:id/actions/precapture — Capture pre-mutation state
  • POST /sessions/:id/actions — Log action
  • PATCH /sessions/:id/actions/:actionId — Update action status
  • GET /approvals/:id — Poll approval status
  • GET /registry — Fetch connector registry capabilities
  • GET /settings/credentials/validate — Validate connector credentials
API key tokens cannot call administrative or operator routes. Attempting to access operator routes (such as policy creation or approval resolution) with an API key returns HTTP 403 with problem type operator-required.

​
Dashboard / Operator Tokens

Human operators log in via the dashboard to obtain operator session tokens. Operator tokens have full access to management features:
  • Managing policies (/policies)
  • Resolving approval requests (/approvals/:id/approve, /approvals/:id/reject)
  • Creating or revoking API keys (/api-keys)
  • Viewing audit logs (/audit-logs), org metrics (/metrics), and intent drift logs (/sessions/:id/intent, /sessions/intent/summary)

​
2. Server Enforcement & Boundaries

SDK Cooperation Guarantee: Server-side policy results and safety tracking are recorded and enforced as far as the SDK cooperates. An agent that bypasses the AgentRein SDK and invokes external APIs directly is not blocked by the server.
  • Pre-execution Blocking: Pre-execution blocking occurs when actions are explicitly declared in wrap() using requiresApproval. The SDK pauses local execution before calling the external provider while polling for approval.
  • After-the-Fact Policy Enforcement: Standard SDK calls evaluate policy rules when logged to POST /sessions/:id/actions. If a policy specifies BLOCK, the backend transitions the action to FAILED and returns HTTP 403. If a policy specifies REQUIRE_APPROVAL, the backend creates an after-execution approval request; if rejected, single-action rollback is triggered.
  • No Pre-Execution Authorize Endpoint: AgentRein does not expose a pre-execution authorization endpoint.

​
3. Resilience & Failure Modes

When initializing the client, the failureMode option controls SDK behavior when communicating with the AgentRein backend or encountering server errors:
  • Standard Calls: For actions not configured in requiresApproval, the external provider call has already executed before action logging occurs. If logging to POST /sessions/:id/actions fails—including network outages, backend errors, or HTTP 403 server denials (such as policy-blocked or plan gate requirements):
    • In failureMode: 'open' (default), the SDK logs a warning (console.warn in Node.js / logging.warning in Python) and returns the provider result without recording the action.
    • In failureMode: 'closed', the SDK re-throws the underlying HTTP error immediately (or raises AgentReinUnavailableError during session completion/rollback), halting execution.
  • requiresApproval Calls: For actions configured in requiresApproval, the SDK attempts to create a pending-approval record via POST /sessions/:id/actions before invoking the external provider. If pending-approval creation fails:
    • In failureMode: 'open', the SDK logs a warning and permits the local provider call to proceed directly without approval gating.
    • In failureMode: 'closed', the SDK re-throws the underlying error immediately, halting execution and preventing the provider call from executing.
Open Mode Swallows Server Denials: In failureMode: 'open' (the default setting), server errors and policy denials during action logging are logged as warnings rather than throwing errors. For requiresApproval calls, open mode bypasses approval creation and permits the provider call to execute unapproved. Use failureMode: 'closed' in high-security environments where unmonitored operations or backend communication failures must strictly halt execution.