Express Bearer Token Middleware

3.0.0 · maintenance · verified Wed Apr 22

express-bearer-token is an Express middleware for extracting RFC6750-compliant OAuth 2.0 bearer tokens from incoming HTTP requests. It attempts to locate a token in the 'Authorization: Bearer <token>' header, the 'access_token' field in the request body, or 'access_token' in query parameters. Optionally, it can also extract tokens from cookies. If found, the token is made available on `req.token`. Crucially, if multiple token sources are present, the middleware strictly adheres to RFC6750 by immediately aborting the request with an HTTP 400 status code. The package is currently at version 3.0.0 and ships with TypeScript types. Its release cadence appears to be slow, with the last major release two years ago, suggesting a mature, maintenance-focused project rather than active feature development.

Common errors

```
Error: secret must be provided when signed is true
```
cause The `cookie.signed` option was set to `true`, but the required `secret` option, used for signing and verifying cookies, was omitted from the configuration.

fix Provide a secret string in the `cookie` configuration object: `bearerToken({ cookie: { signed: true, secret: 'your-super-secret-key' } })`.
```
Property 'token' does not exist on type 'Request'.
```
cause This TypeScript compiler error indicates that `req.token` is not recognized on the Express `Request` interface, often because the package's type augmentations are not being picked up correctly.

fix Ensure `express-bearer-token` is installed and that your `tsconfig.json` properly includes `node_modules/@types` or `express-bearer-token` types in its `typeRoots` or `types` configuration. Sometimes, adding `import 'express-bearer-token';` in a global type definition file (e.g., `src/types.d.ts`) can help resolve type merging issues.

Warnings

breaking The `cookie` option configuration changed in v3.0.0. Specifically, the `key` property within the `cookie` object was removed, and the `name` property was renamed to `key`.
Fix: If configuring cookie token extraction, update your `cookie` configuration to use `key` for the cookie's name, e.g., `{ cookie: { key: 'access_token', signed: true, secret: '...' } }`.
breaking In v2.0.0, the extracted token was stored on `req.bearerToken`. This was changed to `req.token` for brevity and consistency.
Fix: Migrate all references from `req.bearerToken` to `req.token` in your application code.
gotcha By default, `express-bearer-token` strictly adheres to RFC6750. If a bearer token is provided in more than one location (e.g., in the Authorization header and also in the request body), the request will be aborted with an HTTP 400 error.
Fix: Ensure client applications send the bearer token in only one location per request (typically the `Authorization: Bearer` header).
gotcha Using unsigned cookies with the `cookie` option (i.e., `cookie.signed: false`) can make your application vulnerable to cookie spoofing, allowing attackers to modify tokens without detection.
Fix: Always use signed cookies by setting `cookie.signed: true` and providing a strong `secret` to prevent token tampering. Example: `bearerToken({ cookie: { signed: true, secret: 'YOUR_APP_SECRET', key: 'access_token' } })`.

Install

npm install express-bearer-token npm
yarn add express-bearer-token yarn
pnpm add express-bearer-token pnpm

Imports

bearerToken
wrong:
```
import { bearerToken } from 'express-bearer-token'
```
correct:
```
import bearerToken from 'express-bearer-token'
```
The primary export is a default function for ESM. For CommonJS, use `const bearerToken = require('express-bearer-token');`
BearerTokenOptions
wrong:
```
import { BearerTokenOptions } from 'express-bearer-token'
```
correct:
```
import { type BearerTokenOptions } from 'express-bearer-token'
```
Type import for configuring middleware options. Use the `type` keyword for clarity and bundle optimization in TypeScript.
Request (augmented)
```
import 'express-bearer-token'
```
The package augments the Express `Request` interface, adding `req.token`. Simply installing the package and importing the middleware (even implicitly) typically makes this type available in TypeScript projects; sometimes an explicit import is needed in a global declaration file.

Quickstart

Demonstrates basic usage of the `express-bearer-token` middleware to extract a bearer token from various sources and make it available on `req.token` for subsequent route handlers.

import express from 'express';
import bearerToken from 'express-bearer-token';

const app = express();

app.use(bearerToken());

app.get('/', (req, res) => {
  if (req.token) {
    res.send('Token found: ' + req.token);
  } else {
    res.status(401).send('No token provided');
  }
});

app.listen(8000, () => {
  console.log('Server listening on port 8000.\nTest with: `curl -H "Authorization: Bearer mytoken" localhost:8000`');
  console.log('Or: `curl -X POST -d "access_token=bodytoken" localhost:8000`');
});

view raw JSON →