passport-http-custom-bearer

1.0.15 verified Sat Apr 25 auth: no javascript

Passport strategy for HTTP Bearer authentication using custom header, body field, or query parameter names (rather than the standard Authorization header). Version 1.0.15 is the latest stable release; the package sees infrequent updates. It forks passport-http-bearer to allow configurable field names like X-APIAuth or api_token. Key differentiator: flexibility for non-standard token placements, commonly used in legacy or custom API gateway setups. Supports Node >=0.4.0 and works with Express/Connect-style middleware.

Common errors

error TypeError: CustomBearerStrategy is not a constructor ↓

cause Using named import instead of default import in ESM.

fix

Use import CustomBearerStrategy from 'passport-http-custom-bearer' (no curly braces).

error Cannot find module 'passport-http-custom-bearer' ↓

cause Module not installed or typo in package name.

fix

Run npm install passport-http-custom-bearer and verify package.json.

error UnauthorizedError: No auth token ↓

cause Token not found because custom header/field name is not being sent by client.

fix

Ensure client sends token in the expected header (e.g., X-APIAuth), body field (api_token), or query parameter (api_token).

Warnings

gotcha The `headerName` option automatically prepends 'X-' prefix. For example, setting `headerName: 'APIAuth'` expects header `X-APIAuth`. ↓

fix If you want an exact header name without prefix, set headerName to include 'X-' yourself or use a workaround.

deprecated The default strategy name is 'custom-bearer'. In some documentation it's referred to as 'bearer'. ↓

fix Always specify a custom name like 'api-bearer' to avoid confusion.

gotcha The strategy does not automatically strip the token from query or body after authentication. You must manually delete it in a custom callback if needed. ↓

fix Use passport.authenticate with a custom callback and delete req.query[info.queryName] or req.body[info.bodyName].

breaking Passport 0.7+ changed the internal callback signature. This strategy may not work with Passport >=0.7 without adaptation. ↓

fix Use Passport 0.6.x or test with newer versions carefully.

Install

npm install passport-http-custom-bearer

yarn add passport-http-custom-bearer

pnpm add passport-http-custom-bearer

Imports

default (CustomBearerStrategy)

wrong

const { CustomBearerStrategy } = require('passport-http-custom-bearer')

correct

import CustomBearerStrategy from 'passport-http-custom-bearer'

Default export only; named import will return undefined.

Strategy

wrong

import { Strategy } from 'passport-http-custom-bearer'

correct

import Strategy from 'passport-http-custom-bearer'

The module exports the constructor as default; Strategy is not a named export.

require usage

wrong

const { default } = require('passport-http-custom-bearer')

correct

const CustomBearerStrategy = require('passport-http-custom-bearer')

CommonJS require returns the constructor directly, not an object.

Quickstart

Configures CustomBearerStrategy with custom header/body/query field names and uses it in an Express route.

import passport from 'passport';
import CustomBearerStrategy from 'passport-http-custom-bearer';

passport.use('api-bearer', new CustomBearerStrategy(
  {
    headerName: 'APIAuth',
    bodyName: 'api_token',
    queryName: 'api_token'
  },
  (token, done) => {
    // Replace with actual user lookup
    if (token === 'valid-token') {
      return done(null, { id: 1, name: 'John' }, { scope: 'read' });
    }
    return done(null, false);
  }
));

// Express route example
import express from 'express';
const app = express();
app.get('/profile', passport.authenticate('api-bearer', { session: false }), (req, res) => {
  res.json(req.user);
});