{"id":16911,"library":"superagent-d2l-session-auth","title":"Superagent D2L Session Authentication","description":"superagent-d2l-session-auth is a JavaScript plugin designed to integrate D2L (Brightspace) session authentication with `superagent` HTTP requests. It acts as a `superagent` middleware, automatically adding the necessary D2L authentication headers to outbound requests by leveraging the `frau-jwt` library internally. The current stable version is 2.0.1, which includes a fix for `trustedHost` casing sensitivity. While specific release cadence is not explicitly stated, the project appears to be actively maintained by Brightspace, with updates addressing functionality and compatibility. Its primary differentiator is its specialized function within the Brightspace ecosystem, providing a streamlined way to handle D2L session-based authentication for applications using `superagent`, particularly within iframed contexts.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/Brightspace/superagent-d2l-session-auth","tags":["javascript","d2l","free-range","frau","superagent"],"install":[{"cmd":"npm install superagent-d2l-session-auth","lang":"bash","label":"npm"},{"cmd":"yarn add superagent-d2l-session-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add superagent-d2l-session-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a superagent plugin and requires superagent to function. It is a peer dependency.","package":"superagent","optional":false}],"imports":[{"note":"The primary export is a factory function. While the README shows CommonJS, ESM is the modern approach.","wrong":"const auth = require('superagent-d2l-session-auth')","symbol":"auth","correct":"import auth from 'superagent-d2l-session-auth'"},{"note":"The default export is a factory function that must be called to create the plugin instance.","wrong":"const auth = require('superagent-d2l-session-auth')","symbol":"authFactory","correct":"const auth = require('superagent-d2l-session-auth')()"},{"note":"For strictly iframed applications, import from the 'framed' path and call it as a factory function.","wrong":"const auth = require('superagent-d2l-session-auth/framed')","symbol":"framedAuthFactory","correct":"const auth = require('superagent-d2l-session-auth/framed')()"}],"quickstart":{"code":"const request = require('superagent');\nconst auth = require('superagent-d2l-session-auth')({\n    scope: '*:*:*',\n    trustedHost: 'school.brightspace.com' // Replace with your D2L domain\n});\n\n// Example using a placeholder D2L API endpoint\nrequest\n    .get('https://school.brightspace.com/d2l/api/lp/1.5/users/whoami')\n    .use(auth)\n    .end(function(err, res) {\n        if(err) {\n           console.error('Failed to fetch user info: ' + err.status + ' ' + (err.response ? err.response.text : ''));\n           return;\n        }\n        const user = res.body;\n        console.log('Hello, ' + user.FirstName + ' ' + user.LastName);\n    });","lang":"javascript","description":"Demonstrates how to initialize the `superagent-d2l-session-auth` plugin and attach it to a `superagent` request for D2L API interaction."},"warnings":[{"fix":"Ensure `superagent` is installed as a direct dependency in your project: `npm install superagent` or `yarn add superagent`.","message":"Starting from version `0.12.0`, `superagent` was changed to a peer dependency. Users must explicitly install `superagent` in their project, as it is no longer bundled.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Transition to using the standard D2L session authentication flow provided by the plugin, which leverages `frau-jwt` for token management.","message":"The use of the `X-D2L-App-Id` header for authentication was deprecated starting from version `0.1.0`. Relying on this header may lead to authentication failures in newer D2L environments.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"Upgrade to version `1.0.1` or newer. If upgrading is not possible, ensure the `trustedHost` option exactly matches the case of the target D2L host.","message":"Prior to version `1.0.1`, the `trustedHost` option in the plugin configuration was case-sensitive. Incorrect casing could prevent tokens from being sent to the specified host.","severity":"gotcha","affected_versions":"<1.0.1"},{"fix":"For CommonJS environments, use `const auth = require('superagent-d2l-session-auth')()`. For ESM, ensure your project is configured for `type: module` in `package.json` or use a bundler.","message":"The library primarily uses and demonstrates CommonJS `require()` syntax. While bundlers can handle ESM `import` in many environments, direct `import` might fail in older Node.js versions or certain browser contexts without proper module configuration.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run `npm install superagent` or `yarn add superagent` to add `superagent` to your project's dependencies.","cause":"`superagent` is a peer dependency and was not installed in the project.","error":"Error: Cannot find module 'superagent'"},{"fix":"Call the imported `auth` function to get the plugin instance: `const auth = require('superagent-d2l-session-auth')()` or `import createAuth from 'superagent-d2l-session-auth'; const auth = createAuth();`.","cause":"The main export of `superagent-d2l-session-auth` is a factory function that must be called to produce the actual plugin.","error":"TypeError: auth is not a function"},{"fix":"Use ESM `import` syntax: `import createAuth from 'superagent-d2l-session-auth'; const auth = createAuth();`.","cause":"Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) environment (e.g., Node.js with `type: module` or a browser).","error":"ReferenceError: require is not defined"},{"fix":"Use CommonJS `require()` syntax: `const auth = require('superagent-d2l-session-auth')();`.","cause":"Attempting to use ESM `import` syntax in a CommonJS environment (e.g., Node.js without `type: module` in `package.json`).","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm","meta_description":null}