AgentPrismEndpointOptions

Namespace AgentPrism · Assembly AgentPrism.AspNetCore.dll

Access and behavior settings for the endpoints connected via MapAgentPrism.

public sealed class AgentPrismEndpointOptions

Inheritance

object ← AgentPrismEndpointOptions

Inherited Members

object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

Access protection has three layers, applied in this order:

• Loopback restriction — while AgentPrismEndpointOptions.AllowRemoteAccess is off (default), a request from outside loopback gets 403. Protects against accidental exposure to the outside.
• Bearer token — when AgentPrismEndpointOptions.AuthToken is set, the Authorization: Bearer header is checked with a constant-time comparison.
• Authorization policy — AgentPrismEndpointOptions.RequireAuthorization connects to the ASP.NET Core authentication pipeline. This is the path used in production.

This type is deliberately not a record. A record’s compiler-generated ToString writes every property and a single log line would leak the AgentPrismEndpointOptions.AuthToken value.

Constructors

AgentPrismEndpointOptions()

public AgentPrismEndpointOptions()

Properties

AllowRemoteAccess

Whether requests from outside loopback are allowed. Default false.

public bool AllowRemoteAccess { get; set; }

Property Value

bool

Remarks

Reverse proxy warning. If the application sits behind a reverse proxy, the connection’s remote address is the proxy’s address, which is usually loopback. In that case the loopback restriction protects nothing. Behind a reverse proxy, configure the ForwardedHeaders middleware and base protection on AgentPrismEndpointOptions.AuthToken or AgentPrismEndpointOptions.RequireAuthorization.

AllowedOrigins

Origins allowed to call the AgentPrism endpoints from a browser. Empty by default — no Access-Control-Allow-Origin header is ever sent, so a cross-origin browser request is blocked by the browser itself.

public IList<string> AllowedOrigins { get; }

Property Value

IList<string>

Remarks

There is no AllowAnyOrigin option: an endpoint that carries a bearer token or an API key must not make a wildcard origin easy to reach for. Add exact origins, for example options.AllowedOrigins.Add("https://shop.example.com").

This exists for the embeddable chat component: a consumer’s own page, served from its own origin, calls {prefix}/api/agents/{name}/run directly from the browser.

An allowed origin can read a response from any endpoint under {prefix}, not only the run endpoint — CORS is applied to the whole group, not path by path. This is deliberately broad rather than a source of extra privilege WHEN a credential layer is configured: reading a response then requires a valid bearer token or a correctly scoped API key, and CORS only controls whether the browser lets the page’s own script read what that credential already permits. With no credential layer configured - no AgentPrismEndpointOptions.AuthToken and no AgentPrismEndpointOptions.AuthorizationPolicy, which is the default - an allowed origin needs no credential at all, and every script on that origin can read every endpoint under the prefix. Add an origin only where you also control which credential reaches it, and do not add one before the credential layer is on.

AuthToken

Expected bearer token. If left empty, no token check is performed.

public string? AuthToken { get; set; }

Property Value

string?

Remarks

This is a secret. Do not write it to a configuration file; use dotnet user-secrets or an environment variable. The value never appears in any response, in /api/meta output, or in a log line.

AuthorizationPolicy

Name of the ASP.NET Core authorization policy applied to the endpoints. Set via AgentPrismEndpointOptions.RequireAuthorization.

public string? AuthorizationPolicy { get; }

Property Value

string?

EnableDiagnosticsEndpoint

Whether the GET /api/diagnostics endpoint is connected. Default false.

public bool EnableDiagnosticsEndpoint { get; set; }

Property Value

bool

Remarks

A diagnostics endpoint reveals information about the setup (persistence provider, migration status, which configuration keys are resolved) even though it carries no secret value. Per the no-surprises rule it must be explicitly enabled; default off.

When enabled the endpoint requires the AgentPrismPolicies.Admin role. If the role policy is not registered, the endpoint still passes through the three-layer protection (loopback + bearer token).

RequireRolePolicies

Requires that the endpoint role policies (AgentPrismPolicies) be registered in the consumer’s authorization configuration. Default false.

public bool RequireRolePolicies { get; set; }

Property Value

bool

Remarks

When off (default), an unregistered role policy is silently skipped; the corresponding endpoint only passes through the existing three-layer protection. This exists so a version upgrade does not break existing setups.

When on, MapAgentPrism fails at startup if any of the AgentPrism.Reader, AgentPrism.Operator, AgentPrism.Admin policies is not defined via AddAuthorization. A production setup should turn this on; a door left silently open is worse than a door believed to be closed.

RunEventPollInterval

Interval between polls while streaming events for a running run. Default 250 ms.

public TimeSpan RunEventPollInterval { get; set; }

Property Value

TimeSpan

Remarks

The event store offers no notification channel; live streaming is achieved by polling the store for new events. A smaller value reduces latency but increases database load.

Exceptions

ArgumentOutOfRangeException

The value is not positive.

Methods

RequireAuthorization(string)

Attaches the endpoints to an ASP.NET Core authorization policy.

public void RequireAuthorization(string policyName)

Parameters

policyName string

Name of the policy to apply.

Remarks

The policy applies to every endpoint except {prefix}/api/meta. The meta endpoint stays open so the UI can learn which authentication method to use, and it returns no sensitive data.

Exceptions

ArgumentException

policyName is empty.