> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/honojs/hono/llms.txt
> Use this file to discover all available pages before exploring further.

# basicAuth

> API reference for the Basic Auth middleware

## Import

```typescript theme={null}
import { basicAuth } from 'hono/basic-auth'
```

## Usage

```typescript theme={null}
const app = new Hono()

app.use(
  '/auth/*',
  basicAuth({
    username: 'hono',
    password: 'ahotproject',
  })
)

app.get('/auth/page', (c) => {
  return c.text('You are authorized')
})
```

## Options

The `basicAuth` middleware accepts a `BasicAuthOptions` object:

<ParamField path="username" type="string">
  The username for authentication. Required if `verifyUser` is not provided.
</ParamField>

<ParamField path="password" type="string">
  The password for authentication. Required if `verifyUser` is not provided.
</ParamField>

<ParamField path="verifyUser" type="(username: string, password: string, c: Context) => boolean | Promise<boolean>">
  Custom function to verify user credentials. Alternative to providing `username` and `password`.
</ParamField>

<ParamField path="realm" type="string" default="Secure Area">
  The realm attribute for the WWW-Authenticate header.
</ParamField>

<ParamField path="hashFunction" type="Function">
  The hash function used for secure comparison of credentials.
</ParamField>

<ParamField path="invalidUserMessage" type="string | object | MessageFunction" default="Unauthorized">
  The message returned when authentication fails. Can be a string, object, or function that returns either.
</ParamField>

<ParamField path="onAuthSuccess" type="(c: Context, username: string) => void | Promise<void>">
  Callback function called on successful authentication. Useful for setting user context.
</ParamField>

## Signature

```typescript theme={null}
basicAuth(
  options: BasicAuthOptions,
  ...users: { username: string; password: string }[]
): MiddlewareHandler
```

## Examples

### With onAuthSuccess callback

```typescript theme={null}
app.use(
  '/auth/*',
  basicAuth({
    username: 'hono',
    password: 'ahotproject',
    onAuthSuccess: (c, username) => {
      c.set('user', { name: username, role: 'admin' })
      console.log(`User ${username} authenticated`)
    },
  })
)
```

### With custom verifyUser function

```typescript theme={null}
app.use(
  '/auth/*',
  basicAuth({
    verifyUser: async (username, password, c) => {
      // Check credentials against database
      const user = await db.users.findOne({ username })
      return user && await comparePassword(password, user.hashedPassword)
    },
  })
)
```

### Multiple users

```typescript theme={null}
app.use(
  '/auth/*',
  basicAuth(
    { username: 'admin', password: 'secret1' },
    { username: 'user', password: 'secret2' }
  )
)
```

## Behavior

* Returns 401 Unauthorized if credentials are missing or invalid
* Sets `WWW-Authenticate` header with the specified realm
* Uses timing-safe comparison to prevent timing attacks
* Supports custom hash functions for secure credential comparison
* Can validate multiple username/password pairs