Getting Started

Introduction

This library is a standards-compliant OAuth 2.0 authorization server for Node.js, written in TypeScript. It uses JWT and Proof Key for Code Exchange (PKCE).

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.