# AI Agent Architecture And Security > Mailrith uses one public resource model, least-privilege credentials, typed operations, exact action approval, existing delivery safeguards, and compact redacted activity across every supported agent client. - Human page: https://mailrith.com/developers/agent-security - Markdown page: https://mailrith.com/developers/agent-security.md - Category: AI Agent Platform - Reading time: 10 min read - Last updated: 2026-07-22 - Related keywords: AI Agent Architecture And Security, AI Agent Architecture And Security developer docs, AI Agent Platform, AI Agent Platform developer docs, Mailrith developer docs, Mailrith public API, Architecture And Trust Boundaries, Permissions And Authentication, Security And Data Handling, Audit And Investigation, Troubleshooting, AI Agent Quickstarts, AI Agent Client Compatibility, Authentication ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## What this guide covers Understand Mailrith's agent architecture, trust boundaries, permissions, OAuth, approval controls, redacted audit trail, and troubleshooting flow. ## Architecture And Trust Boundaries Mailrith keeps one public resource model across REST, the generated SDKs, CLI, and MCP tools. Machine-readable discovery describes the same operations; it does not add an agent-only write or delivery path. Treat the model and agent runtime as untrusted input. OAuth or a workspace API key establishes the connection, workspace permissions limit available operations, typed schemas validate input, and existing Mailrith domain services enforce Subscriber, sender, provider, preflight, and delivery rules. High-impact actions cross a separate plan and approval boundary. Activity records correlate authorization, plan, approval, execution, and outcome without storing full Subscriber payloads, message bodies, secrets, or approval tokens. - Discovery: llms files, API catalog, API version, OpenAPI, capabilities, MCP server card, and Agent Skill. - Connection: OAuth with resource binding for user-connected clients; narrow workspace API keys for trusted server-side jobs. - Operation: typed REST or MCP tools call the existing Subscriber, campaign, workflow, and delivery services. - Control: workspace policy, exact previews, human approval where required, single-use tokens, revocation, and emergency controls. - Observation: bounded redacted activity, request IDs, action IDs, progress, and final outcomes. ## Permissions And Authentication Use OAuth when a person connects Mailrith to OpenAI, Claude, Codex, or another user-facing client. The authorization flow uses PKCE, exact redirect validation, state checking, resource binding, refresh-token rotation, and revocation. Use an API key only in a trusted server-side runtime. Create one key per integration, choose the smallest task preset, set an expiration, and rotate or revoke that key without affecting other connections. 1. Call capability discovery with the credential before selecting tools. 2. Compare required operation scopes with the granted workspace permissions. 3. Expose a small client tool allowlist. Do not rely on a prompt to prevent disallowed calls. 4. Revoke a connection immediately if its owner, runtime, callback address, or task changes unexpectedly. ## Security And Data Handling Never put API keys, OAuth tokens, approval tokens, Subscriber exports, or full email bodies in prompts, URLs, traces, screenshots, or logs. Store credentials in the client secret store and pass them only in authorization headers. Mailrith activity stores compact identifiers, risk, decision, timing, and redacted outcome metadata. Detailed content remains in its normal Mailrith resource instead of being copied into an append-only agent log. Provider-side tool approval is an additional safeguard, not a replacement for Mailrith permissions and exact action approval. A compromised client cannot expand the scopes on its existing credential. ## Audit And Investigation Start an investigation with one request ID or action ID. In Agent Control, filter activity by connection, operation, risk, decision, or outcome. Open the matching action to see plan timing, approver, expiration, and execution state. If an outcome is uncertain, inspect the target and progress endpoint before retrying. Repeating a high-impact operation without checking can create a second logical action even when the first request reached Mailrith. 1. Revoke the connection if compromise is possible. 2. Record the request ID, action ID, connection, operation, and time range. 3. Review redacted activity and the target resource's current state. 4. Check delivery progress or job status when the operation is asynchronous. 5. Create a new plan only after the owner confirms that the original action did not complete and still should run. ## Troubleshooting For connection failures, check the server URL, OAuth callback, token expiration, resource binding, and requested scopes. For a missing tool, check capability discovery, credential permissions, client allowlists, and the selected MCP toolsets. For a denied action, read the stable error code and request ID. Do not retry validation, permission, policy, approval, stale-target, or preflight errors without changing the cause. - `401`: reconnect or rotate the credential; do not repeat the secret in logs. - `403`: request the missing task permission from a workspace owner or remove the operation. - `409`: inspect idempotency, stale target, action state, or uncertain outcome before retrying. - `422`: correct the typed input or blocking preflight issue. - `429` or a temporary `5xx`: honor retry guidance and keep pagination and polling bounded. ## Related Guides - [AI Agent Quickstarts](https://mailrith.com/developers/agent-quickstarts.md): Follow four task-based paths for a five-minute read, campaign drafting, an exact approval-based live send, and isolated sandbox testing without giving an agent broad workspace control. - [AI Agent Client Compatibility](https://mailrith.com/developers/agent-compatibility.md): Use the current compatibility matrix and read-only starter configurations, then record live conformance against an exact client build or review date before making a support claim. - [Authentication](https://mailrith.com/developers/authentication.md): Every protected `v1` request is authorized through a workspace-scoped API key. This page covers the required header shape, workspace scoping behavior, and authentication failure handling.