{"id":17736,"library":"koa-bearer-token","title":"Koa Bearer Token Middleware","description":"koa-bearer-token is a middleware for Koa.js that parses bearer tokens from incoming requests, adhering to RFC6750. It extracts tokens from the `Authorization: Bearer <token>` header, `access_token` query parameter, or `access_token` in the request body. Since version 2.0.0, it also supports extracting tokens from signed or unsigned cookies. The current stable version is 2.0.2, released in August 2021, suggesting a maintenance or slow-cadence release schedule. Key differentiators include its strict RFC6750 compliance, extensive configurability for token keys and locations, and built-in TypeScript support. It integrates seamlessly with Koa applications, making it straightforward to secure API endpoints with OAuth2 bearer tokens. It requires Node.js version 12 or higher.","status":"maintenance","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/chentsulin/koa-bearer-token","tags":["javascript","bearer","koa","middleware","oauth","token","typescript"],"install":[{"cmd":"npm install koa-bearer-token","lang":"bash","label":"npm"},{"cmd":"yarn add koa-bearer-token","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-bearer-token","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency as a Koa middleware. Requires Koa >= 2.","package":"koa","optional":false},{"reason":"Required if tokens are expected in the request body.","package":"koa-bodyparser","optional":true}],"imports":[{"note":"Since v2.0.0, the package uses named exports. Default imports will not work.","wrong":"import bearerToken from 'koa-bearer-token';","symbol":"bearerToken","correct":"import { bearerToken } from 'koa-bearer-token';"},{"note":"For CommonJS, use destructuring assignment to import the named export 'bearerToken' since v2.0.0.","wrong":"const bearerToken = require('koa-bearer-token');","symbol":"bearerToken","correct":"const { bearerToken } = require('koa-bearer-token');"},{"note":"For custom `reqKey` configurations in TypeScript, module augmentation is required to extend Koa's `Request` interface.","symbol":"Request","correct":"declare module 'koa' { interface Request { myToken?: string; } }"}],"quickstart":{"code":"import Koa from 'koa';\nimport bodyParser from 'koa-bodyparser';\nimport { bearerToken } from 'koa-bearer-token';\n\nconst app = new Koa();\n\napp.use(bodyParser());\napp.use(bearerToken({\n  cookie: {\n    signed: false, // Set to true if using signed cookies and provide a secret\n    secret: process.env.COOKIE_SECRET ?? '', // Required if signed is true\n    key: 'auth_token', // Custom cookie key\n  },\n  reqKey: 'myCustomToken',\n}));\n\napp.use((ctx) => {\n  if (ctx.request.myCustomToken) {\n    ctx.body = `Token found: ${ctx.request.myCustomToken}`;\n  } else {\n    ctx.status = 401;\n    ctx.body = 'Authentication required';\n  }\n});\n\napp.listen(3000, () => {\n  console.log('Koa app listening on port 3000');\n});","lang":"typescript","description":"Demonstrates setting up `koa-bearer-token` middleware with custom options, including cookie extraction and a custom request key, and then accessing the token within a Koa route handler."},"warnings":[{"fix":"Update CommonJS imports to `const { bearerToken } = require('koa-bearer-token');` and ESM imports to `import { bearerToken } from 'koa-bearer-token';`.","message":"Version 2.0.0 introduced a breaking change by switching from default export to named export. Code using `require('koa-bearer-token')` or `import bearerToken from 'koa-bearer-token'` will fail.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your Node.js environment is version 12 or newer. Update Node.js or use a compatible version of the library (e.g., 1.x.x for Node < 12).","message":"Version 2.0.0 raised the minimum Node.js requirement to version 12. Applications running on older Node.js versions will encounter compatibility issues.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always use `{ signed: true }` for cookie parsing and provide a `secret` to ensure cookie integrity and prevent tampering: `bearerToken({ cookie: { signed: true, secret: 'YOUR_APP_SECRET' } })`.","message":"When extracting tokens from cookies, failing to pass `{ signed: true }` makes your application vulnerable to cookie spoofing, as it will accept non-signed cookies.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure client applications send the bearer token in only one location (header, query, body, or cookie) to avoid 400 errors. This is intended RFC compliance, not a bug.","message":"If a token is found in more than one location (e.g., header and query), the middleware will abort the request with a 400 Bad Request status code, per RFC6750.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Change the import statement from `import bearerToken from 'koa-bearer-token';` to `import { bearerToken } from 'koa-bearer-token';`.","cause":"Attempting to import `koa-bearer-token` using a default import syntax in ESM after v2.0.0.","error":"TypeError: (0, _koaBearertoken.default) is not a function"},{"fix":"Change the CommonJS require statement from `const bearerToken = require('koa-bearer-token');` to `const { bearerToken } = require('koa-bearer-token');`.","cause":"Attempting to `require('koa-bearer-token')` as a default export in CommonJS after v2.0.0.","error":"TypeError: bearerToken is not a function"},{"fix":"Provide a strong secret string via the `cookie.secret` option: `bearerToken({ cookie: { signed: true, secret: 'YOUR_APP_SECRET' } })`.","cause":"When `cookie.signed` is set to `true`, the `secret` option is mandatory for cookie signing/unsigning.","error":"Error: You must pass secret option in order to sign/unsign cookie"},{"fix":"Perform module augmentation to extend the Koa `Request` interface: `declare module 'koa' { interface Request { [myToken]?: string; } }`.","cause":"When using a custom `reqKey` (e.g., `reqKey: 'myToken'`) in TypeScript, the Koa `Request` interface does not automatically know about this new property.","error":"Property 'token' does not exist on type 'Request'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}