# How Bearer Authentication is Configured in the OpenAPI Schema

> Learn how to configure bearer authentication in OpenAPI schema using Hono by registering a bearerAuth component for JWT token authorization across all API endpoints.

- Repository: [Lucas Zanoni⠀⠀⠀⠀⠀ ⠀╱|、 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ (˚ˎ 。7 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ |、˜〵 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ じしˍ,)ノ/tcc](https://github.com/castrozan/tcc)
- Tags: how-to-guide
- Published: 2026-02-27

---

**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`](https://github.com/castrozan/tcc/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/castrozan/tcc/blob/main/professionals-dummy-app/src/infrastructure/web/open-api/server.ts), the server initialization combines the global security requirement with the component registration:

```typescript
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`](https://github.com/castrozan/tcc/blob/main/equipments-dummy-app/src/infrastructure/web/open-api/server.ts) file mirrors this configuration exactly:

```typescript
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:

```yaml
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`](https://github.com/castrozan/tcc/blob/main/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.