Node.js Quickstart

Use this guide to add ThunderID authentication to a Node.js service using the @thunderid/node SDK.

What You Will Learn

• Create a Node.js project

• Install the @thunderid/node package

• Authenticate a service with the client_credentials grant

• Use the resulting access token to call business logic

Prerequisites

• About 10 minutes

• Node.js 18+ installed on your system

• npm, yarn, or pnpm

• Your preferred code editor

1

Run ThunderID

Start a local ThunderID instance. Pick the method that works best for you:

$npx thunderid

Requires Node.js 18+

Full install guide →

Once it's running, the console is available at https://localhost:8090/console.

2

Create an Application

1. Sign in to the Console.

   Test User

   If you used the default setup, sign in to the Console as admin with the password generated during setup and printed to the setup output (unless you supplied your own).

2. Navigate to Applications.

3. Click Add Application.

4. From the Choose a type page, select Backend Service.

5. Enter a name (e.g. My Node.js Service).

6. Click Create.

Machine-to-Machine

Backend Service applications are pre-configured for the client_credentials grant with client_secret_basic authentication. No OAuth 2.0 redirect URI or extra setup is needed.

Note

Copy the Client ID from the General tab, and the Client Secret from the window that pops up when the application is created; it's shown only once (if lost, regenerate it from the application's Credentials tab).

3

Create a Node.js Project

Initialize a new Node.js project:

npm

mkdir my-node-service
cd my-node-service
npm init -y

Yarn

mkdir my-node-service
cd my-node-service
yarn init -y

pnpm

mkdir my-node-service
cd my-node-service
pnpm init

4

Install @thunderid/node

Install the ThunderID Node.js SDK:

npm

npm install @thunderid/node

Yarn

yarn add @thunderid/node

pnpm

pnpm add @thunderid/node

5

Authenticate as the Service

Create an index.mjs file and initialize ThunderIDNodeClient with grantType: 'client_credentials'. With that set, getAccessToken() authenticates as the service itself, no session and no sign-in, and transparently fetches, caches, and refreshes the token.

index.mjs

import { ThunderIDNodeClient } from '@thunderid/node';

const client = new ThunderIDNodeClient();

await client.initialize({
  baseUrl: 'https://localhost:8090',
  clientId: '<your-client-id>',
  clientSecret: '<your-client-secret>',
  grantType: 'client_credentials',
});

const accessToken = await client.getAccessToken();
const { scope } = await client.decodeJwtToken(accessToken);

console.log(`Authenticated with scope: ${scope}`);

Configuration

Replace <your-client-id> and <your-client-secret> with the Client ID and Client Secret from your ThunderID application.

Configuration Parameters

Parameter	Description
baseUrl	Your ThunderID instance URL (e.g., https://localhost:8090)
clientId	The Client ID from your ThunderID application
clientSecret	The Client Secret from your ThunderID application
grantType	Set to 'client_credentials' to authenticate the service as itself, with no user and no browser redirect

6

Call Business Logic With the Token

A real backend keeps authentication in its own module instead of scattering it across business logic. Update index.mjs so the rest of the app asks for a token only when it needs one, instead of handling getAccessToken() and the Authorization header directly:

index.mjs

import { ThunderIDNodeClient } from '@thunderid/node';

const client = new ThunderIDNodeClient();

await client.initialize({
  baseUrl: 'https://localhost:8090',
  clientId: '<your-client-id>',
  clientSecret: '<your-client-secret>',
  grantType: 'client_credentials',
});

async function getStock(sku) {
  const accessToken = await client.getAccessToken();

  // A real backend would attach this as `Authorization: Bearer ${accessToken}`
  // on a request to a separate inventory service. This quickstart just proves
  // the token was obtained before answering.
  console.log(`Requesting ${sku} with a valid access token`);

  return { sku, inStock: true };
}

const item = await getStock('SKU-100');
console.log(item);

7

Run Your Service

Start the script:

npm

node index.mjs

Yarn

yarn node index.mjs

pnpm

pnpm node index.mjs

Success

The script authenticates once, prints the scope it received, then calls getStock() and prints the result before exiting.

What's Next

Agent AuthenticationRequest specific scopes, narrow tokens to a resource server, and troubleshoot the token endpoint directly.Read the Guide →

Node.js SDK ReferenceExplore the full API reference for the Node.js SDK.API Reference →