# IToolAuthorizationHandler

> 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.itoolauthorizationhandler/
> Summary: IToolAuthorizationHandler: Decides whether a tenant/user may call a specific tool.

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

Decides whether a tenant/user may call a specific tool.

```csharp
public interface IToolAuthorizationHandler
```

## Remarks

This is separate from approval ([ToolDescriptor.RequiresApproval](/api/tracon.tooldescriptor/#Tracon_ToolDescriptor_RequiresApproval)).
Approval asks a human "is this call okay this time"; this interface asks
the installation's own policy "can this caller call this tool at all".
Both can apply to the same tool; when they do, authorization runs first —
asking a human to approve a call the caller could never make anyway is
backwards.

The default implementation (`AllowAllToolAuthorizationHandler`,
registered with `TryAdd`) allows every call, so an installation that
registers nothing keeps today's behavior exactly. A consumer replaces the
registration to enforce its own rule.

If this handler throws, the call is **denied** (fail-closed).
A gate that fails open on an exception is not a gate.

The handler is asked for every call that runs through Tracon's tool chain: a tool registered in code, a tool of an
MCP server, the `file_access_*` tools of a session workspace ([ToolEffect.Read](/api/tracon.tooleffect/),
[ToolEffect.Write](/api/tracon.tooleffect/) or [ToolEffect.Destructive](/api/tracon.tooleffect/)), `search_knowledge` and the
`search_conversation_memory` tool of an on-demand conversation memory (both [ToolEffect.External](/api/tracon.tooleffect/):
the text of the query leaves the process). The last three are not in [IToolRegistry](/api/tracon.itoolregistry/), so their names are
not listed by `GET /api/tools`. The handler is not asked for a hosted tool (it runs at the model provider), an
agent called as a tool, a skill tool, the file memory, todo and harness tools, or a tool that a provider added by an
agent extension brings.

## Methods

### <a id="Tracon_IToolAuthorizationHandler_AuthorizeAsync_Tracon_ToolAuthorizationRequest_System_Threading_CancellationToken_"></a> AuthorizeAsync\(ToolAuthorizationRequest, CancellationToken\)

Decides whether the call described by `request` may proceed.

```csharp
ValueTask<ToolAuthorizationResult> AuthorizeAsync(ToolAuthorizationRequest request, CancellationToken cancellationToken = default)
```

#### Parameters

`request` [ToolAuthorizationRequest](/api/tracon.toolauthorizationrequest/)

The call being authorized.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[ToolAuthorizationResult](/api/tracon.toolauthorizationresult/)\>

The decision.