---
title: authorize
sidebarTitle: authorize
---

# `fastmcp.server.auth.handlers.authorize`


Enhanced authorization handler with improved error responses.

This module provides an enhanced authorization handler that wraps the MCP SDK's
AuthorizationHandler to provide better error messages when clients attempt to
authorize with unregistered client IDs.

The enhancement adds:
- Content negotiation: HTML for browsers, JSON for API clients
- Enhanced JSON responses with registration endpoint hints
- Styled HTML error pages with registration links/forms
- Link headers pointing to registration endpoints


## Functions

### `create_unregistered_client_html` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/handlers/authorize.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_unregistered_client_html(client_id: str, registration_endpoint: str, discovery_endpoint: str, server_name: str | None = None, server_icon_url: str | None = None, title: str = 'Client Not Registered') -> str
```


Create styled HTML error page for unregistered client attempts.

**Args:**
- `client_id`: The unregistered client ID that was provided
- `registration_endpoint`: URL of the registration endpoint
- `discovery_endpoint`: URL of the OAuth metadata discovery endpoint
- `server_name`: Optional server name for branding
- `server_icon_url`: Optional server icon URL
- `title`: Page title

**Returns:**
- HTML string for the error page


## Classes

### `AuthorizationHandler` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/handlers/authorize.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Authorization handler with enhanced error responses for unregistered clients.

This handler extends the MCP SDK's AuthorizationHandler to provide better UX
when clients attempt to authorize without being registered. It implements
content negotiation to return:

- HTML error pages for browser requests
- Enhanced JSON with registration hints for API clients
- Link headers pointing to registration endpoints

This maintains OAuth 2.1 compliance (returns 400 for invalid client_id)
while providing actionable guidance to fix the error.


**Methods:**

#### `handle` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/handlers/authorize.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
handle(self, request: Request) -> Response
```

Handle authorization request with enhanced error responses.

This method extends the SDK's authorization handler and intercepts
errors for unregistered clients to provide better error responses
based on the client's Accept header.

**Args:**
- `request`: The authorization request

**Returns:**
- Response (redirect on success, error response on failure)

