[Hackathon] Docs: add a canonical V2 authentication and API versioning guide

[GagandeepSingh20]

Problem Statement

HydraDB V2 authentication and API-versioning information is currently spread
across multiple documentation pages instead of being available through one
canonical guide.

For example:

• The V2 Quickstart shows how to get an API key and authenticate SDK and cURL
  requests.
• The API Reference states that endpoints require Bearer authentication.
• The SDK guide explains that official SDKs automatically send
  API-Version: 2.
• The Error Responses page separately explains authentication failures and
  version-header requirements.

A developer therefore has to combine information from several pages to answer
a basic integration question:

Get an API key
→ store it securely
→ authenticate a raw HTTP request
→ understand API-Version: 2
→ initialize an SDK client
→ troubleshoot 401 and 403 responses

The V2 API Documentation navigation currently has no dedicated Authentication
page. This makes authentication harder to discover and increases the chance of
developers omitting the version header on raw HTTP requests or misunderstanding
authentication and authorization errors.

Proposed Solution

Add a canonical V2 authentication guide at:

api-reference/v2/authentication.mdx

The page would document the complete authentication journey:

1. Getting an API key from the HydraDB dashboard.

2. Storing the key in the HYDRA_DB_API_KEY environment variable.

3. Authenticating raw HTTP requests with:

   Authorization: Bearer <api-key>
   API-Version: 2

4. Showing a minimal authenticated request to GET /databases.

5. Initializing the official Python and TypeScript SDK clients.

6. Clarifying that the official SDKs automatically send API-Version: 2.

7. Explaining the difference between:

   • 401 Unauthorized: missing, expired, or invalid credentials
   • 403 Forbidden: valid authentication without access to the requested
     resource or operation

8. Providing safe API-key handling guidance.

9. Adding a practical authentication checklist.

The implementation would also:

• Add the new page to the V2 API Documentation navigation in docs.json.
• Link to it from the V2 Quickstart.
• Link to it from the V2 API Reference index.
• Link to it from the SDK guide.
• Link to it from the Error Responses troubleshooting section.

This would be a documentation-only change. It would not modify API endpoints,
authentication behavior, permissions, SDK behavior, or version routing.

Alternatives Considered

Keep the information distributed across the existing pages

The required information technically exists, but developers have to discover
and combine several independent sections. It also leaves no canonical page that
other guides, support responses, or tools can reference.

Expand only the Quickstart

The Quickstart should remain focused on reaching the first successful request.
Adding complete authentication, versioning, troubleshooting, and secret-handling
details would make the onboarding flow unnecessarily long.

Add the information only to Error Responses

The Error Responses page is useful after a request fails, but it is not the
natural starting point for developers configuring authentication for the first
time.

Document only raw HTTP authentication

This would not explain the important difference between raw HTTP requests,
which require API-Version: 2, and official SDK requests, which add the version
header automatically.

A dedicated guide with contextual cross-links provides the clearest and most
maintainable solution.

Additional Context

The proposed page consolidates behavior that is already documented across the
repository rather than introducing new product claims.

The implementation has been prepared and verified locally:

• The new authentication page renders successfully in Mintlify.
• The page is visible in the V2 API Documentation sidebar.
• The cURL, Python, and TypeScript examples render correctly.
• The authentication header and 401/403 tables render correctly.
• Cross-links from the Quickstart, API Reference, SDK guide, and Error
  Responses page resolve successfully.
• docs.json passes JSON validation.
• git diff --check passes.
• No API key or credential has been committed.

The scope is limited to these six files:

• api-reference/v2/authentication.mdx
• api-reference/v2/index.mdx
• api-reference/v2/sdks.mdx
• api-reference/v2/error-responses.mdx
• get-started/v2/quickstart.mdx
• docs.json

This does not overlap with the broader beginner developer journey work, which
links to existing detailed references. This proposal creates the dedicated
authentication reference that those journeys and other documentation pages can
link to.

A focused documentation-only implementation is ready locally and can be opened
as a linked PR.