# TraconEndpointOptions

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.traconendpointoptions/
> Summary: TraconEndpointOptions: Access and behavior settings for the endpoints connected via MapTracon.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.AspNetCore.dll</code></div>

Access and behavior settings for the endpoints connected via `MapTracon`.

```csharp
public sealed class TraconEndpointOptions
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.traconendpointoptions/">TraconEndpointOptions</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## Remarks

Access protection has three layers, applied in this order:

- **Loopback restriction** — while [TraconEndpointOptions.AllowRemoteAccess](/api/tracon.traconendpointoptions/#Tracon_TraconEndpointOptions_AllowRemoteAccess) is off (default), a request from outside loopback gets `403`. Protects against accidental exposure to the outside.
- **Bearer token** — when [TraconEndpointOptions.AuthToken](/api/tracon.traconendpointoptions/#Tracon_TraconEndpointOptions_AuthToken) is set, the `Authorization: Bearer` header is checked with a constant-time comparison.
- **Authorization policy** — [TraconEndpointOptions.RequireAuthorization](/api/tracon.traconendpointoptions/#Tracon_TraconEndpointOptions_RequireAuthorization_System_String_) 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](/api/tracon.traconendpointoptions/#Tracon_TraconEndpointOptions_AuthToken) value.

## Constructors

### <a id="Tracon_TraconEndpointOptions__ctor"></a> TraconEndpointOptions\(\)

```csharp
public TraconEndpointOptions()
```

## Properties

### <a id="Tracon_TraconEndpointOptions_AllowRemoteAccess"></a> AllowRemoteAccess

Whether requests from outside loopback are allowed. Default
[false](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool).

```csharp
public bool AllowRemoteAccess { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### 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](/api/tracon.traconendpointoptions/#Tracon_TraconEndpointOptions_AuthToken) or [TraconEndpointOptions.RequireAuthorization](/api/tracon.traconendpointoptions/#Tracon_TraconEndpointOptions_RequireAuthorization_System_String_).

### <a id="Tracon_TraconEndpointOptions_AllowedOrigins"></a> 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.

```csharp
public IList<string> AllowedOrigins { get; }
```

#### Property Value

 [IList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ilist\-1)<[string](https://learn.microsoft.com/dotnet/api/system.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](/api/tracon.traconendpointoptions/#Tracon_TraconEndpointOptions_AuthToken) and no [TraconEndpointOptions.AuthorizationPolicy](/api/tracon.traconendpointoptions/#Tracon_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.

### <a id="Tracon_TraconEndpointOptions_AuthToken"></a> AuthToken

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

```csharp
public string? AuthToken { get; set; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.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.

### <a id="Tracon_TraconEndpointOptions_AuthorizationPolicy"></a> AuthorizationPolicy

Name of the ASP.NET Core authorization policy applied to the endpoints.
Set via [TraconEndpointOptions.RequireAuthorization](/api/tracon.traconendpointoptions/#Tracon_TraconEndpointOptions_RequireAuthorization_System_String_).

```csharp
public string? AuthorizationPolicy { get; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_TraconEndpointOptions_EnableDiagnosticsEndpoint"></a> EnableDiagnosticsEndpoint

Whether the `GET /api/diagnostics` endpoint is connected. Default
[false](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool).

```csharp
public bool EnableDiagnosticsEndpoint { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### 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](/api/tracon.traconpolicies/#Tracon_TraconPolicies_Admin)
role. If the role policy is not registered, the endpoint still passes
through the three-layer protection (loopback + bearer token).

### <a id="Tracon_TraconEndpointOptions_MapOpenAIConversations"></a> MapOpenAIConversations

Whether the OpenAI-compatible `/v1/conversations` endpoints are
connected. Default [true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool).

```csharp
public bool MapOpenAIConversations { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### 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](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) 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](/api/tracon.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.

### <a id="Tracon_TraconEndpointOptions_RequireRolePolicies"></a> RequireRolePolicies

Requires that the endpoint role policies ([TraconPolicies](/api/tracon.traconpolicies/))
be registered in the consumer's authorization configuration. Default
[false](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool).

```csharp
public bool RequireRolePolicies { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### 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.

### <a id="Tracon_TraconEndpointOptions_RunEventPollInterval"></a> RunEventPollInterval

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

```csharp
public TimeSpan RunEventPollInterval { get; set; }
```

#### Property Value

 [TimeSpan](https://learn.microsoft.com/dotnet/api/system.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](https://learn.microsoft.com/dotnet/api/system.argumentoutofrangeexception)

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

### <a id="Tracon_TraconEndpointOptions_StreamKeepAliveInterval"></a> 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.

```csharp
public TimeSpan StreamKeepAliveInterval { get; set; }
```

#### Property Value

 [TimeSpan](https://learn.microsoft.com/dotnet/api/system.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](https://learn.microsoft.com/dotnet/api/system.argumentoutofrangeexception)

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

## Methods

### <a id="Tracon_TraconEndpointOptions_RequireAuthorization_System_String_"></a> RequireAuthorization\(string\)

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

```csharp
public void RequireAuthorization(string policyName)
```

#### Parameters

`policyName` [string](https://learn.microsoft.com/dotnet/api/system.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](https://learn.microsoft.com/dotnet/api/system.argumentexception)

`policyName` is empty.