Getting Started

Introduction

This library is a standards-compliant OAuth 2.0 authorization server for Node.js, written in TypeScript. It issues signed JWT Access Tokens, enforces PKCE by default, and adds an optional OpenID Connect layer. It implements RFC 6749 and its companion RFCs for bearer tokens, revocation, introspection, and token exchange.

The library is framework-agnostic, and it does not own your storage or your routes. You write a small set of repositories for your database, and you connect each endpoint to one server method. Adapters for Express, Fastify, and H3 convert the request and response objects of your framework.

The library needs Node.js 22 or later.

Quick Start

1. Install the package
2. Write your entities
3. Create your database schema
4. Write your repositories
5. Create the AuthorizationServer with the grants you need
6. Add the endpoints

Installation

pnpm

pnpm add @jmondi/oauth2-server

npm

npm install --save @jmondi/oauth2-server

yarn

yarn add @jmondi/oauth2-server

jsr

npx jsr add @jmondi/oauth2-server

deno

deno add @jmondi/oauth2-server

bun

bunx jsr add @jmondi/oauth2-server

Write the Entities and Repositories

The library does not store data. You write the entities that hold the data, and the repositories that read and write it.

Create the Authorization Server

The AuthorizationServer takes your client, token, and scope repositories, and a signing secret. The constructor enables the client_credentials and refresh_token grants. You must enable each of the other grants.

const authorizationServer = new AuthorizationServer(
  clientRepository,
  accessTokenRepository,
  scopeRepository,
  "secret-key",
);
authorizationServer.enableGrantType({
  grant: "authorization_code",
  userRepository,
  authCodeRepository,
});

Configuration lists the options. Grants helps you select a flow.

Add the Endpoints

You control the routes. Each endpoint calls one method on the server.

Route	Method	Required for
/token	respondToAccessTokenRequest	Every grant
/authorize	validateAuthorizationRequest → completeAuthorizationRequest	Authorization code, implicit
/token/revoke	revoke	Optional (RFC 7009)
/token/introspect	introspect	Optional (RFC 7662)
/userinfo · /jwks · discovery	userInfo, jwks, openidConfiguration	OIDC

Use an adapter to convert your framework's request and response objects.

Security

Serve every endpoint over HTTPS. Hash each client secret before you store it. The library enforces PKCE by default.

When your server issues tokens, read Protecting Resources. It shows you how to validate the tokens in your API.