Authenticating Agent Calls to Your Backend APIs
How to forward OAuth, session, embed, and custom credentials when agents invoke Actions—without oversimplifying to a single token type.
Agents that call your APIs must act as a specific user or service—not as an anonymous superuser. Authentication for agent → backend traffic is about forwarding the right credentials for the right Environment, scoping Actions tightly, and keeping secrets out of prompts.
The Core Pattern: Forward, Don't Invent
When a user talks to an agent embedded in your App, your frontend already knows who they are. The agent platform should forward that identity to your backends when Actions run:
const response = await fetch('https://api.meebly.ai/v1/chat', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'YOUR_API_KEY',
'X-Backend-Token': userAccessToken, // OAuth access token, session token, etc.
},
body: JSON.stringify({
agentId: 'support-agent',
environmentId: 'production',
messages: [{ content: 'Update my shipping address' }],
}),
});
Your Action endpoints then authorize exactly as they would for a normal first-party client.
Credential Types That Show Up in Practice
Production systems rarely use one auth style everywhere. Agents should support the schemes your App already uses.
OAuth access tokens
Common for SaaS APIs and third-party integrations. The agent receives a short-lived access token (and refresh is handled by your app or token broker). Scopes on the token should match the Actions you expose—do not hand the agent a token that can delete the entire tenant if it only needs read access.
Session tokens / cookies
Many first-party apps authenticate with opaque session tokens. Forward the session credential on Action calls and validate it server-side the same way your web app does. Prefer HttpOnly cookies or short-lived session headers over putting session material in model context.
Embed tokens
Widget and iframe deployments often mint a scoped embed token for the Meebly session: tied to a user, tenant, and expiry. Embed tokens should be narrowly scoped to the Actions available in that Environment and easy to revoke when the widget unmounts.
Custom / internal schemes
Enterprise backends may use mTLS, signed request headers, or API-key-plus-user assertion patterns. Configure those per Environment so sandbox uses staging trust roots and production uses live ones. Document the scheme in Action setup so operators know what "authenticated" means.
What Never Belongs in the Prompt
Do not paste credentials into system instructions or user messages. Models may echo them into Traces, logs, or replies. Keep secrets in:
- Request headers (
X-Backend-Tokenor your configured auth header) - Environment-level connection settings for MCP servers and Actions
- Your own token broker that exchanges a session for a short-lived backend credential
Least Privilege for Actions
Auth is necessary but not sufficient. Pair credentials with Action design:
- Separate read and write tools
- Enable HITL for privileged writes even when the caller is authenticated
- Validate resource ownership in the backend (
order.userId === session.userId) - Use Tool Monitoring to catch cross-tenant parameter anomalies
An authenticated agent can still call the wrong ID. Server-side authorization remains mandatory.
Environment-Specific Auth
Sandbox and production should use different credential sources:
- Sandbox → staging OAuth clients, test session stores, non-production embed issuers
- Production → live clients and stricter token TTLs
Promoting an App between Environments should never silently reuse sandbox credentials against production APIs.
Handling Expiry and Re-Auth
Access tokens and sessions expire mid-conversation. Plan for it:
{
"ok": false,
"code": "AUTH_EXPIRED",
"message": "Session expired",
"userMessage": "Please sign in again to continue."
}
Teach the agent (via instructions) to stop retrying and ask the user to re-authenticate when it sees AUTH_EXPIRED, instead of looping tool calls.
Auditing Who Did What
Tie every Action invocation to:
- The end-user or service principal
- The agent and Environment
- The run ID in Traces
- Whether HITL approval occurred
Security reviews need that chain when an agent-initiated change looks suspicious.
Conclusion
Authenticating agent backend calls means forwarding OAuth access tokens, session tokens, embed tokens, or custom credentials—whichever your App already trusts—while keeping secrets out of prompts and enforcing authorization on every Action. Meebly Environments and Action configuration exist so auth stays explicit, scoped, and auditable as agents move from sandbox to production.
