> ## Documentation Index
> Fetch the complete documentation index at: https://agentrein.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Model & Authentication

> Authentication scopes, API key permissions, server guarantees, and failure modes.

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

<Warning>
  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`.
</Warning>

### 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

<Warning>
  **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.
</Warning>

* **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.

<Warning>
  **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.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.