FastAPI like login?

[joa23]

Hi,
Is there a way to add login to the spotlight page similar to the FastAPI docs. That is super convenient.
What would one need to do that to implement this or did I just miss to set this up?
Thanks.

[danielgtaylor]

@joa23 do you have an example of how that works in FastAPI I can look at?

[joa23]

Thanks Daniel. Example screen shots attached.


Happy to do some leg work if you point me the right direction.

[wolveix]

Hi @joa23! Sorry this sat for so long.

Yes, this functionality is supported natively by Huma! Here's an example:

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/danielgtaylor/huma/v2"
	"github.com/danielgtaylor/huma/v2/adapters/humachi"
	"github.com/danielgtaylor/huma/v2/humacli"
	"github.com/go-chi/chi/v5"
)

// Options for the CLI.
type Options struct {
	Port int `help:"Port to listen on" short:"p" default:"8888"`
}

// TokenInput represents the OAuth2 token request (RFC 6749 section 4.3.2).
// Huma will automatically handle `application/x-www-form-urlencoded` for this.
type TokenInput struct {
	Body struct {
		GrantType    string `json:"grant_type" doc:"The type of grant being requested. Must be 'password'."`
		Username     string `json:"username" doc:"The user's username."`
		Password     string `json:"password" doc:"The user's password."`
		Scope        string `json:"scope" doc:"Optional requested scopes."`
		ClientID     string `json:"client_id" doc:"Optional client ID."`
		ClientSecret string `json:"client_secret" doc:"Optional client secret."`
	}
}

// TokenOutput represents the OAuth2 token response.
type TokenOutput struct {
	Body struct {
		AccessToken string `json:"access_token" doc:"The issued access token."`
		TokenType   string `json:"token_type" doc:"The type of token, e.g. 'Bearer'."`
		ExpiresIn   int    `json:"expires_in" doc:"Lifetime in seconds."`
	}
}

// ProtectedInput represents a request to a protected resource.
type ProtectedInput struct{}

// ProtectedOutput represents the response from a protected resource.
type ProtectedOutput struct {
	Body struct {
		Message string `json:"message" doc:"A secret message only for authorized users."`
	}
}

func main() {
	// Create a CLI app which takes a port option.
	cli := humacli.New(func(hooks humacli.Hooks, options *Options) {
		// Create a new router & API
		router := chi.NewMux()
		cfg := huma.DefaultConfig("OAuth2 Password Flow API", "1.0.0")
		cfg.DocsRenderer = huma.DocsRendererSwaggerUI

		// 1. Define the security scheme in the OpenAPI components.
		if cfg.OpenAPI.Components == nil {
			cfg.OpenAPI.Components = &huma.Components{}
		}
		if cfg.OpenAPI.Components.SecuritySchemes == nil {
			cfg.OpenAPI.Components.SecuritySchemes = make(map[string]*huma.SecurityScheme)
		}
		cfg.OpenAPI.Components.SecuritySchemes["oauth2Password"] = &huma.SecurityScheme{
			Type: "oauth2",
			Flows: &huma.OAuthFlows{
				Password: &huma.OAuthFlow{
					TokenURL: "/token",
					Scopes: map[string]string{
						"read":  "Read access",
						"write": "Write access",
					},
				},
			},
		}

		api := humachi.New(router, cfg)

		// 2. Register the token endpoint.
		// This endpoint is used by the OpenAPI UI to get a token.
		huma.Register(api, huma.Operation{
			OperationID:   "PostToken",
			Summary:       "OAuth2 Token Endpoint",
			Description:   "Exchange username and password for an access token.",
			Method:        http.MethodPost,
			Path:          "/token",
			DefaultStatus: http.StatusOK,
		}, func(ctx context.Context, input *TokenInput) (*TokenOutput, error) {
			// In a real app, you would verify the username/password here.
			if input.Body.Username == "" || input.Body.Password == "" {
				return nil, huma.Error401Unauthorized("Invalid username or password")
			}

			fmt.Printf("Token requested for user: %s\n", input.Body.Username)

			resp := &TokenOutput{}
			resp.Body.AccessToken = "mock-token-123"
			resp.Body.TokenType = "Bearer"
			resp.Body.ExpiresIn = 3600
			return resp, nil
		})

		// 3. Register a protected endpoint.
		huma.Register(api, huma.Operation{
			OperationID: "GetProtected",
			Summary:     "Protected Resource",
			Description: "An endpoint that requires OAuth2 password authentication.",
			Method:      http.MethodGet,
			Path:        "/secure",
			// Link this operation to the security scheme defined above.
			Security: []map[string][]string{
				{"oauth2Password": {"read"}},
			},
		}, func(ctx context.Context, input *ProtectedInput) (*ProtectedOutput, error) {
			// In a real app, you would use middleware to verify the token
			// and potentially put the user info into the context.
			// Huma doesn't automatically verify tokens; you must provide middleware.

			resp := &ProtectedOutput{}
			resp.Body.Message = "Hello, you are authorized!"
			return resp, nil
		})

		// Tell the CLI how to start your router.
		hooks.OnStart(func() {
			fmt.Printf("Starting server on port %d...\n", options.Port)
			fmt.Printf("OpenAPI spec available at: http://localhost:%d/openapi.yaml\n", options.Port)
			fmt.Printf("OpenAPI UI available at: http://localhost:%d/docs\n", options.Port)
			http.ListenAndServe(fmt.Sprintf(":%d", options.Port), router)
		})
	})

	// Run the CLI.
	cli.Run()
}