Authentication & security

Choose credentials based on who owns the action

A public catalog needs no credential. “My bookings” needs the signed-in user's token. A server-only partner lookup may need a service API key. These are different authorities, not interchangeable configuration styles.

In the booking fixture, the host supplies auth.token, and request.auth.type: session adds a Bearer header at execution. Without that token the runtime does not manufacture an identity; it can send the request without the header and leave rejection to the API. Therefore, enforce sign-in in your host before starting protected operations.

For service keys, configure an environment variable name under env; changing its header name changes the HTTP header, not the privilege the key grants. A missing required service key fails configuration compilation.

Verify the boundary with your API

Test the same operation with a valid token, an expired token, another user's resource ID, and no token. Expect the API to enforce ownership, and handle its 401/403 through AUTH_REJECTED. Then test account switching: allocate a new authorized conversation or clear the old session rather than carrying pending approval into a different identity.

Keep credentials out of browser-authored config, model input, mapped headers, and ordinary context. Runtime redaction supplements your application's access control; it cannot replace it.

AGENTO is not your auth server

The current Runtime intentionally does not decode user JWTs, fetch JWKS keys, validate issuers/audiences, or decide business permissions.

Your downstream API remains authoritative for:

• token validity and expiry;
• login state;
• roles/scopes;
• tenant boundaries;
• resource ownership;
• business authorization.

User-authenticated tools

request:
  auth:
    type: session

Then the trusted host passes the caller's token:

const result = await runtime.invoke({
  sessionId: serverOwnedSessionId,
  tool: "my-bookings",
  auth: { token: userAccessToken },
});

At execution time AGENTO forwards:

Authorization: Bearer <opaque-token>

The token is not intended for model prompts, model-facing schemas, ordinary session context, results, or hooks.

401 and 403

Upstream 401 and 403 responses are surfaced as AUTH_REJECTED, with the bounded upstream status available in error details. Your host decides whether that means “sign in again,” “refresh login,” or “you are not allowed.”

Session ID is not identity

This is a critical production rule:

A sessionId is a conversation/continuation handle, not proof of identity.

The host must bind server-owned session IDs to callers. Do not let a client arbitrarily choose another user's session ID or attach a different user's token to an existing session.

For account switching, clear the old session or allocate a fresh server-owned session ID.

API-key tools

For server-to-server credentials:

request:
  auth:
    type: api-key
    env: SERVICE_KEY
    header: X-API-Key

The compiler expects the environment variable to exist. Do not put service keys in URLs, user arguments or prompts.

Public tools

request:
  auth:
    type: none

Use only when the endpoint is genuinely public.

Session credential reuse

AGENTO can retain an opaque session token so later select()/confirm() continuations can use it. The exported authentication contract supports a custom SessionTokenStore; stored token values are encrypted before the store sees them.

With a custom store, provide a shared 32-byte encryption key to workers that must reuse credentials across instances.

Redaction

Runtime redaction protects known secrets and sensitive fields across results, history, hooks and model-bound data. It is a transport safeguard, not a full PII classifier.

Your API must still return only data appropriate for the caller and apply domain-specific minimization.

Transport safeguards

• credential-bearing requests require HTTPS unless local development explicitly opts out;
• redirects are blocked;
• runtime validates the final request origin against configured origin;
• response bodies have byte ceilings;
• model-facing projections are bounded;
• credentials cannot be declared as normal model input fields.