Documenting API Authentication

Relevant source files

The following files were used as context for generating this wiki page:

• api-reference/openapi.json
• docs.json
• README.md
• api-reference/introduction.mdx (Referenced in docs.json)
• essentials/navigation.mdx (Referenced in docs.json)

This document outlines how API authentication is defined and documented for the "OpenAPI Plant Store" project. The primary source for the API's structure, including its security mechanisms, is the OpenAPI 3.1.0 specification file. The project employs a global authentication strategy, requiring a bearer token for all API endpoints.

The documentation itself is structured using Mintlify, with configuration defined in docs.json. This ensures that API security information is presented clearly to developers within the generated API reference pages.

Global Authentication Strategy

The API enforces authentication globally across all endpoints. This is specified by the top-level security object in the OpenAPI definition, which mandates the use of the bearerAuth scheme for all requests. Any request made to an endpoint without proper authentication will be rejected.

Sources: api-reference/openapi.json:20-23

Request Authentication Flow

The following diagram illustrates the high-level flow for an incoming API request, showing how the global security requirement is checked before the request is processed.

Security Scheme Definition

The project defines a single security scheme named bearerAuth. This scheme is configured to use HTTP Bearer authentication (typically used for JWTs), as defined in the components.securitySchemes section of the OpenAPI file.

Sources: api-reference/openapi.json:205-211

Bearer Authentication (bearerAuth)

This is the primary and only authentication method for the API. Clients must include a valid token in the Authorization header of their requests.

The diagram below shows the sequence for a client making an authenticated request to the /plants endpoint.

Scheme Details

The configuration details for the bearerAuth scheme are as follows:

Property	Value	Description
type	http	Specifies that this is an HTTP-based scheme.
scheme	bearer	Specifies the Bearer (token) authentication scheme.

Sources: api-reference/openapi.json:207-209

The corresponding JSON definition within the OpenAPI specification is:

"securitySchemes": {
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer"
  }
}

Sources: api-reference/openapi.json:206-211

API Documentation Structure

The structure of the final generated documentation is defined in docs.json. This file organizes content into tabs, groups, and pages, ensuring that users can easily navigate to the API reference to understand authentication requirements.

Sources: docs.json

API Reference Tab

The docs.json file configures an "API reference" tab which contains all endpoint documentation. This section is crucial for developers to understand how to interact with the API, including how to authenticate.

Group	Pages	Purpose
API documentation	api-reference/introduction	Provides an introduction to the API, likely including auth basics.
Endpoint examples	get, create, delete, webhook	Demonstrates usage for specific endpoints, which are all secured.

Sources: docs.json:44-59, api-reference/introduction.mdx

The navigation structure ensures that introductory materials and specific endpoint examples are grouped logically, guiding the developer from general concepts to practical implementation.

Sources: docs.json:28-35, essentials/navigation.mdx

Local Preview

Developers can preview the documentation, including the authenticated API endpoints, by running a local development server. This is accomplished using the Mintlify CLI.

# Install the Mintlify CLI globally
npm i -g mint

# Run the local development server from the repository root
mint dev

The local preview will be available at http://localhost:3000, allowing for verification of the documented security requirements before publishing.

Sources: README.md:13-21