TraconEndpointOptions

Namespace Tracon · Assembly Tracon.AspNetCore.dll

Access and behavior settings for the endpoints connected via MapTracon.

public sealed class TraconEndpointOptions

Inheritance

object ← TraconEndpointOptions

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 TraconEndpointOptions.AllowRemoteAccess is off (default), a request from outside loopback gets 403. Protects against accidental exposure to the outside.
• Bearer token — when TraconEndpointOptions.AuthToken is set, the Authorization: Bearer header is checked with a constant-time comparison.
• Authorization policy — TraconEndpointOptions.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 TraconEndpointOptions.AuthToken value.

Constructors

TraconEndpointOptions()

public TraconEndpointOptions()

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 TraconEndpointOptions.AuthToken or TraconEndpointOptions.RequireAuthorization.

AllowedOrigins

Origins allowed to call the Tracon 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 TraconEndpointOptions.AuthToken and no TraconEndpointOptions.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 TraconEndpointOptions.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 TraconPolicies.Admin role. If the role policy is not registered, the endpoint still passes through the three-layer protection (loopback + bearer token).

MapOpenAIConversations

Whether the OpenAI-compatible /v1/conversations endpoints are connected. Default true.

public bool MapOpenAIConversations { get; set; }

Property Value

bool

Remarks

These four endpoints exist so an OpenAI client library can list, read and delete a conversation by the same identifier it passes to /v1/responses. A deployment that drives Tracon only through its own /api/sessions routes never calls them, and turning them off removes the routes entirely: the paths answer 404 and vanish from the OpenAPI document.

Default true because the surface has shipped and silently withdrawing it would break existing clients. It is a switch for a deployment that wants a smaller attack surface, not a security control: the endpoints go through the same role policies, API key scopes, session ownership and IRunAuthorizationHandler gate as every other session route, and leaving them mapped opens no door that /api/sessions does not open already.

The other OpenAI-compatible surfaces — /v1/responses and /v1/chat/completions — are not governed by this flag. They start runs rather than reach a stored conversation, and a deployment that wants them gone should not have to give up the conversation routes to say so.

RequireRolePolicies

Requires that the endpoint role policies (TraconPolicies) 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, MapTracon fails at startup if any of the Tracon.Reader, Tracon.Operator, Tracon.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.

A policy provider that THROWS while a role name is resolved is treated as “not registered” in both modes. It is written to the log as a warning (category Tracon.RolePolicies); when this option is on, the startup exception carries the provider’s exception as its inner exception.

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 outside one millisecond to about 49.7 days, the range the poll delay accepts.

StreamKeepAliveInterval

The longest a server-sent event stream stays silent. When nothing else has been written for this long, the stream writes a keep-alive comment. Default 15 seconds.

public TimeSpan StreamKeepAliveInterval { get; set; }

Property Value

TimeSpan

Remarks

Applies to every streaming endpoint: agent runs, workflow runs, resumes and responses, and the OpenAI-compatible endpoints. A run whose producer is busy but quiet (a long workflow node, a slow tool call) would otherwise send no bytes, and a reader with an idle limit would take the silence for a dead connection: the console stops reading after 30 seconds, and a reverse proxy after its read timeout. A closed connection cancels the run.

Keep the value below the shortest idle timeout between the server and its readers, and below 30 seconds while the console is in use. The keep-alive is an SSE comment line, which SSE readers ignore.

Exceptions

ArgumentOutOfRangeException

The value is outside one millisecond to about 49.7 days, the range the delay accepts.

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.