passage-node

This Node.js SDK allows for verification of server-side authentication for applications using Passage.

Install this package using npm.

npm i @passageidentity/passage-node

Authenticating a Request

To authenticate an HTTP request, you can use the Passage SDK to check a request for a valid authentication token. authenticateRequest can handle requests in the format of IncomingMessage, as used by common Node frameworks like Express or with the Next.js page router, and it can also handle requests formatted as a fetch Request, as used by tools like the Next.js app router or Deno. You need to provide Passage with your App ID in order to verify the JWTs.

importPassagefrom'@passageidentity/passage-node';importexpressfrom'express';constapp=express();constport=3000;letpassageConfig={appID: 'YOUR_APP_ID',};// example of custom middlewareletpassage=newPassage(passageConfig);letpassageAuthMiddleware=(()=>{returnasync(req,res,next)=>{awaitpassage.authenticateRequest(req).then((userID)=>{if(userID){res.userID=userID;returnnext();}elsereturnres.status(401).send('unauthorized');}).catch(()=>{returnres.status(401).send('Could not authenticate user!');});};})();// example implementation of custom middlewareapp.get('/authenticatedRoute',passageAuthMiddleware,async(req,res)=>{// authenticated userletuserID=res.userID;});app.listen(port,()=>{console.log(`Example app running`);});

Retrieve App Info

To retrieve information about an app, you should use the passage.getApp() function.

importPassagefrom'@passageidentity/passage-node';letpassageConfig={appID: 'YOUR_APP_ID',};letpassage=newPassage(passageConfig);letpassageApp=awaitpassage.getApp();

Retrieve User Info

To retrieve information about a user, you should use the passage.user.get() function. You will need to use a Passage API key, which can be created in the Passage Console under your Application Settings. This API key grants your web server access to the Passage management APIs to get and update information about users. This API key must be protected and stored in an appropriate secure storage location. It should never be hard-coded in the repository.

importPassagefrom'@passageidentity/passage-node';importexpressfrom'express';constapp=express();constport=3000;letpassageConfig={appID: 'YOUR_APP_ID',apiKey: 'YOUR_API_KEY',};letpassage=newPassage(passageConfig);// example authenticated routeapp.get('/authenticatedRoute',passageAuthMiddleware,async(req,res)=>{// get passage user ID from middlewareletuserID=res.userID;// get user infoletpassageUser=awaitpassage.user.get(userID);console.log(passageUser.email);});

Activate/Deactivate User

You can also activate or deactivate a user using the Passage SDK. These actions require an API Key and deactivating a user will prevent them from logging into your application with Passage.

importPassagefrom'@passageidentity/passage-node';importexpressfrom'express';constapp=express();constport=3000;letpassageConfig={appID: 'YOUR_APP_ID',apiKey: 'YOUR_API_KEY',};letpassage=newPassage(passageConfig);// example authenticated routeapp.get('/authenticatedRoute',passageAuthMiddleware,async(req,res)=>{// get passage user ID from middlewareletuserID=res.userID;// deactivate userletpassageUser=awaitpassage.user.deactivate(userID);console.log(passageUser.activate);});

Update User Attributes

With the Passage SDK, you can update a User's attributes. These actions require an API Key and deactivating a user will prevent them from logging into your application with Passage.

importPassagefrom'@passageidentity/passage-node';importexpressfrom'express';constapp=express();constport=3000;letpassageConfig={appID: 'YOUR_APP_ID',apiKey: 'YOUR_API_KEY',};letpassage=newPassage(passageConfig);// example authenticated routeapp.get('/authenticatedRoute',passageAuthMiddleware,async(req,res)=>{// get passage user ID from middlewareletuserID=res.userID;letnewAttributes={email: 'newEmail@domain.com',phone: '+15005550006',// note that user_metadata is an optional field and is defined in your Passage App settings.user_metadata: {examplefield: 123,},};// update user attributesletpassageUser=awaitpassage.user.update(userID,newAttributes);console.log(passageUser);});

Delete A User

To delete a Passage user, you will need to provide the userID, and corresponding app credentials.

importPassagefrom'@passageidentity/passage-node';importexpressfrom'express';constapp=express();constport=3000;letpassageConfig={appID: 'YOUR_APP_ID',apiKey: 'YOUR_API_KEY',};letpassage=newPassage(passageConfig);// example authenticated routeapp.get('/authenticatedRoute',passageAuthMiddleware,async(req,res)=>{// get passage user ID from middlewareletuserID=res.userID;// deactivate userletdeletedPassageUser=awaitpassage.user.delete(userID);console.log(deletedPassageUser);// true});

Create A User

You can also create a Passage user by providing an email or phone (phone number must be a valid E164 phone number).

importPassagefrom'@passageidentity/passage-node';letpassageConfig={appID: 'YOUR_APP_ID',apiKey: 'YOUR_API_KEY',};letpassage=newPassage(passageConfig);// note that user_metadata is an optional field and is defined in your Passage App settings.letnewPassageUser1=passage.user.create({email: 'newEmail@domain.com',user_metadata: {examplefield: 123,},});console.log(newPassageUser1);// [userObject]letnewPassageUser2=passage.user.create({phone: '+15005550006',});console.log(newPassageUser2);// [userObject]

Create A Magic Link

You can also create a Passage magic link by providing a MagicLinkRequest type

importPassagefrom'@passageidentity/passage-node';letpassageConfig={appID: 'YOUR_APP_ID',apiKey: 'YOUR_API_KEY',};letpassage=newPassage(passageConfig);letmagicLink=passage.createMagicLink({email: 'newEmail@domain.com',channel: 'email',});