docs: document missing HTTP status codes and response shapes

[github-actions]

Summary

Fills documentation gaps in README.md identified during a documentation sweep. No code changes — README only.

Changes

AuthHandler

• Signup — added 201 Created status note (was undocumented)
• Logout — added success response body {"message":"logged out"}
• ChangePassword — added success response body {"message":"password updated"}
• RefreshToken — added note that 404 is returned when Sessions is nil

APIKeyHandler

• Delete — added 204 No Content success status note (consistent with SessionHandler docs style)

PasskeyHandler

• Enabled — added inline response shape {"enabled": true|false} in route table
• BeginRegistration / BeginAuthentication — added inline response shape {"session_id":"...","options":{...}} in route table
• DeleteCredential — added 204 No Content success status note
• Added a Response types paragraph documenting the begin-ceremony response JSON object (session_id + options), explaining how session_id maps to the finish endpoint query parameter and how options maps to the browser WebAuthn API call

Why it matters

The passkey two-step ceremony (BeginRegistration → FinishRegistration, BeginAuthentication → FinishAuthentication) requires clients to:

1. Extract session_id from the begin response and pass it as a query parameter to the finish endpoint
2. Pass options directly to navigator.credentials.create / navigator.credentials.get

Neither the response shape nor this flow was documented, making it impossible to implement without reading the source code.

Generated by Update Docs · ● 1.7M · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/update-docs.md@96b9d4c39aa22359c0b38265927eadb31dcf4e2a

Greptile Summary

Documentation-only PR that fills gaps in README.md for AuthHandler, APIKeyHandler, and PasskeyHandler. All added status codes and response shapes were verified against the actual handler implementations and are accurate.

Confidence Score: 5/5

Safe to merge — documentation-only change with no code modifications.

Every documented status code and response shape was cross-checked against the corresponding handler implementation and found to be correct. No code is changed, so there is no regression risk.

No files require special attention.

Important Files Changed

Filename	Overview
README.md	Adds missing HTTP status codes and response bodies for Auth, APIKey, and Passkey handlers; all documented values verified accurate against source code.

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant S as goauth Server
    participant PS as PasskeyStore

    rect rgb(200, 220, 255)
        Note over C,PS: Registration Ceremony
        C->>S: POST /auth/passkey/register/begin
        S->>PS: Store challenge
        S-->>C: 200 {session_id, options: PublicKeyCredentialCreationOptions}
        C->>C: navigator.credentials.create(options)
        C->>S: POST /auth/passkey/register/finish?session_id=id
        S->>PS: Load and delete challenge
        S-->>C: 201 PasskeyCredentialDTO
    end

    rect rgb(220, 255, 220)
        Note over C,PS: Authentication Ceremony
        C->>S: POST /auth/passkey/login/begin
        S->>PS: Store challenge
        S-->>C: 200 {session_id, options: PublicKeyCredentialRequestOptions}
        C->>C: navigator.credentials.get(options)
        C->>S: POST /auth/passkey/login/finish?session_id=id
        S->>PS: Load and delete challenge
        S-->>C: 200 AuthResponse token + user + HttpOnly cookie
    end

Loading

_{Reviews (3): Last reviewed commit: "docs: merge main — combine prose and rou..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Updates README.md to fill gaps in documented HTTP status codes and response bodies/shapes for key auth, API key, and passkey endpoints, making it easier for clients to implement against the API without reading server source.

Changes:

• Document missing success status codes (e.g., 201 Created, 204 No Content) for Signup, APIKey.Create, APIKey.Delete, and passkey credential delete.
• Document success response bodies for Logout and ChangePassword.
• Document passkey begin-ceremony response shape (session_id + options) and how it maps to the finish endpoints and WebAuthn browser APIs.

Show a summary per file

File	Description
README.md	Adds missing HTTP status notes and response shapes for Auth/API key/Passkey handler endpoints, including passkey begin-ceremony response documentation.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 1/1 changed files
• Comments generated: 1

[veverkap]

Fixed: updated the JSON comment to use the proper WebAuthn type names PublicKeyCredentialCreationOptions and PublicKeyCredentialRequestOptions.