Skip to main content

​
Import

import { bearerAuth } from 'hono/bearer-auth'

​
Usage

const app = new Hono()

const token = 'honoishot'

app.use('/api/*', bearerAuth({ token }))

app.get('/api/page', (c) => {
  return c.json({ message: 'You are authorized' })
})

​
Options

The bearerAuth middleware accepts a BearerAuthOptions object:
​
token
string | string[]
The token or array of tokens to validate against. Required if verifyToken is not provided.
​
verifyToken
(token: string, c: Context) => boolean | Promise<boolean>
Custom function to verify the token. Alternative to providing static token values.
​
realm
string
default:""
The domain name of the realm, as part of the returned WWW-Authenticate challenge header.
​
prefix
string
default:"Bearer"
The prefix (or schema) for the Authorization header value. If set to empty string, no prefix is expected.
​
headerName
string
default:"Authorization"
The header name to look for the token.
​
hashFunction
Function
A function to handle hashing for safe comparison of authentication tokens.
​
noAuthenticationHeader.message
string | object | MessageFunction
default:"Unauthorized"
The message returned when no authentication header is provided.
​
noAuthenticationHeader.wwwAuthenticateHeader
string | object | MessageFunction
default:"Bearer realm=\"\""
The WWW-Authenticate header value when no authentication header is provided.
​
invalidAuthenticationHeader.message
string | object | MessageFunction
default:"Bad Request"
The message returned when authentication header format is invalid.
​
invalidAuthenticationHeader.wwwAuthenticateHeader
string | object | MessageFunction
default:"Bearer error=\"invalid_request\""
The WWW-Authenticate header value when authentication header is invalid.
​
invalidToken.message
string | object | MessageFunction
default:"Unauthorized"
The message returned when token is invalid.
​
invalidToken.wwwAuthenticateHeader
string | object | MessageFunction
default:"Bearer error=\"invalid_token\""
The WWW-Authenticate header value when token is invalid.

​
Signature

bearerAuth(options: BearerAuthOptions): MiddlewareHandler

​
Examples

​
Multiple tokens

app.use('/api/*', bearerAuth({ 
  token: ['token1', 'token2', 'token3'] 
}))

​
Custom token verification

app.use('/api/*', bearerAuth({
  verifyToken: async (token, c) => {
    // Verify against database or external service
    const valid = await validateTokenInDatabase(token)
    return valid
  },
}))

​
Custom prefix

// Use "Token" instead of "Bearer"
app.use('/api/*', bearerAuth({ 
  token: 'secret',
  prefix: 'Token'
}))

// Request header: Authorization: Token secret

​
No prefix

app.use('/api/*', bearerAuth({ 
  token: 'secret',
  prefix: ''
}))

// Request header: Authorization: secret

​
Custom error messages

app.use('/api/*', bearerAuth({
  token: 'secret',
  noAuthenticationHeader: {
    message: 'Please provide authentication',
    wwwAuthenticateHeader: 'Bearer realm="api"'
  },
  invalidToken: {
    message: { error: 'Invalid token provided' }
  }
}))

​
Behavior

  • Returns 401 Unauthorized if token is missing or invalid
  • Returns 400 Bad Request if Authorization header format is invalid
  • Sets WWW-Authenticate header with appropriate error information
  • Uses timing-safe comparison to prevent timing attacks
  • Supports custom hash functions for secure token comparison

Build docs developers (and LLMs) love

Get started for freeTalk to us