How Bearer Authentication is Configured in the OpenAPI Schema

Bearer authentication is configured by passing a security array to the schema option in fromHono and registering a bearerAuth component via openapi.registry.registerComponent with type http and scheme bearer to enable JWT token authorization across all API endpoints.

The castrozan/tcc repository implements a consistent authentication strategy across its microservices using Hono and the Chanfana library. Both the professionals and equipments dummy applications configure bearer token authentication directly in the OpenAPI schema, ensuring that every endpoint requires a valid JWT token by default.

Global Security Requirement Configuration

The foundation of bearer authentication starts with the schema object passed to the fromHono factory function. In src/infrastructure/web/open-api/server.ts, the configuration establishes a global security requirement that applies to all operations unless explicitly overridden.

The security array contains a single object specifying bearerAuth with an empty array, indicating that this security scheme applies to all endpoints without specific scopes:

const openapi = fromHono(app, {
  docs_url: '/',
  schema: {
    security: [{ bearerAuth: [] }]
  }
});

This declaration ensures that the generated OpenAPI specification includes a top-level security field, making bearer token authentication mandatory for all routes defined in the application.

Registering the BearerAuth Security Component

While the global requirement declares that authentication is needed, the actual definition of the bearer scheme occurs through the OpenAPI registry. The code registers a security scheme component named bearerAuth using the registerComponent method:

openapi.registry.registerComponent('securitySchemes', 'bearerAuth', {
  type: 'http',
  scheme: 'bearer'
});

This registration creates a reusable security scheme definition under components.securitySchemes in the final OpenAPI document. The type: 'http' and scheme: 'bearer' values conform to the OpenAPI 3.0 specification for HTTP Bearer authentication, instructing clients to transmit tokens in the Authorization header using the Bearer prefix.

Implementation Across Service Modules

Both microservices in the repository utilize identical authentication patterns, ensuring API consistency.

Professionals Dummy Application

In professionals-dummy-app/src/infrastructure/web/open-api/server.ts, the server initialization combines the global security requirement with the component registration:

import { fromHono } from 'chanfana';
import { Hono } from 'hono';

const app = new Hono();
const openapi = fromHono(app, {
  docs_url: '/',
  schema: {
    security: [{ bearerAuth: [] }]
  }
});

openapi.registry.registerComponent('securitySchemes', 'bearerAuth', {
  type: 'http',
  scheme: 'bearer'
});

Equipments Dummy Application

The equipments-dummy-app/src/infrastructure/web/open-api/server.ts file mirrors this configuration exactly:

import { fromHono } from 'chanfana';
import { Hono } from 'hono';

const app = new Hono();
const openapi = fromHono(app, {
  docs_url: '/',
  schema: {
    security: [{ bearerAuth: [] }]
  }
});

openapi.registry.registerComponent('securitySchemes', 'bearerAuth', {
  type: 'http',
  scheme: 'bearer'
});

Generated OpenAPI Specification Structure

When the documentation endpoint serves the OpenAPI specification at the configured docs_url, the resulting JSON or YAML document contains the security definitions at the root level:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

security:
  - bearerAuth: []

This structure indicates that all operations inherit the bearerAuth requirement. Clients must include Authorization: Bearer <token> headers in requests to endpoints like GET /public/professional or GET /public/equipment.

Summary

• Global security requirement: The schema.security array in fromHono configuration applies bearer authentication to all endpoints by default.
• Component registration: The openapi.registry.registerComponent method defines the bearerAuth scheme with type: 'http' and scheme: 'bearer'.
• Unified implementation: Both professionals-dummy-app and equipments-dummy-app use identical configurations in their respective src/infrastructure/web/open-api/server.ts files.
• OpenAPI compliance: The generated spec follows the OpenAPI 3.0 standard for HTTP Bearer authentication, expecting JWT tokens in the Authorization header.

Frequently Asked Questions

How does the bearer token get transmitted in API requests?

Clients must include the token in the Authorization header using the Bearer prefix, formatted as Authorization: Bearer <jwt_token>. The Chanfana-generated OpenAPI schema expects this format based on the bearerAuth component configuration with type: 'http' and scheme: 'bearer'.

Can specific endpoints bypass the global bearer authentication requirement?

Yes, individual route handlers can override the global security setting by specifying their own security array in the operation configuration. Endpoints that set security: [] explicitly disable authentication for that specific operation, though the repository configures all routes to require bearer tokens by default.

Which library handles the OpenAPI schema generation in this repository?

The repository uses Chanfana (fromHono) to generate OpenAPI 3.0 specifications from Hono applications. This library wraps Hono routes and automatically builds the OpenAPI document based on the provided schema configuration and registered components.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}