Installation & Quick Start

Installation

npm install @authrim/server

Or with other package managers:

pnpm add @authrim/server
yarn add @authrim/server

Prerequisites

Before using @authrim/server, you need:

1. An Authrim instance — A running Authrim authorization server (or any OAuth 2.0/OIDC-compliant issuer)
2. A registered OAuth client — The client application that will acquire tokens and call your API
3. An audience value — A URI that identifies your resource server (e.g., https://api.example.com)

AuthrimServer Initialization

Create and initialize an AuthrimServer instance:

import { AuthrimServer } from '@authrim/server';

const authrim = new AuthrimServer({
  // Required: your authorization server's issuer URL
  issuer: 'https://auth.example.com',

  // Required: your resource server's audience identifier
  audience: 'https://api.example.com',
});

// Call init() once at application startup
await authrim.init();

Call init() Once at Startup

The init() method fetches the authorization server’s OIDC Discovery document and JWKS (JSON Web Key Set). Call it once when your server starts — not on every request. The SDK caches keys automatically and handles rotation.

Configuration Options

Option	Type	Default	Description
issuer	string | string[]	—	Trusted issuer URL(s). Required.
audience	string | string[]	—	Expected audience value(s). Required.
jwksUri	string	Auto-discovered	JWKS endpoint URL. Overrides auto-discovery.
clockToleranceSeconds	number	60	Clock skew tolerance for exp/nbf/iat claims.
jwksRefreshIntervalMs	number	3600000 (1h)	Minimum interval between JWKS refreshes.
introspectionEndpoint	string	—	Token introspection endpoint URL.
revocationEndpoint	string	—	Token revocation endpoint URL.
clientCredentials	object	—	{ clientId, clientSecret } for introspection/revocation.
requireHttps	boolean	true	Enforce HTTPS for all external URLs.

End-to-End Quick Start: Express API

Here is a complete Express API server that validates access tokens and protects an endpoint:

import express from 'express';
import { AuthrimServer } from '@authrim/server';
import { authrimMiddleware } from '@authrim/server/adapters/express';

const app = express();

// 1. Create and initialize AuthrimServer
const authrim = new AuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});

await authrim.init();

// 2. Public endpoint — no authentication required
app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

// 3. Protected endpoint — requires valid access token
app.get('/api/profile', authrimMiddleware(authrim), (req, res) => {
  const token = req.auth;
  res.json({
    userId: token.claims.sub,
    scope: token.claims.scope,
    tokenType: token.tokenType,
  });
});

// 4. Protected endpoint with required scopes
app.get('/api/admin/users', authrimMiddleware(authrim, { requiredScopes: ['admin:read'] }), (req, res) => {
  res.json({ users: [] });
});

app.listen(3000, () => {
  console.log('API server running on http://localhost:3000');
});

This server:

• Fetches and caches the authorization server’s public keys on startup
• Validates JWT access tokens on protected routes
• Checks required scopes when specified
• Makes the validated token available via req.auth

Quick Start: Hono + Cloudflare Workers

@authrim/server works on edge runtimes. Here is a Hono application for Cloudflare Workers:

import { Hono } from 'hono';
import { AuthrimServer } from '@authrim/server';
import { authrimMiddleware, getAuth } from '@authrim/server/adapters/hono';

type Env = {
  ISSUER: string;
  AUDIENCE: string;
};

const app = new Hono<{ Bindings: Env }>();

// Initialize AuthrimServer per request (Workers are stateless)
app.use('/api/*', async (c, next) => {
  const authrim = new AuthrimServer({
    issuer: c.env.ISSUER,
    audience: c.env.AUDIENCE,
  });
  await authrim.init();

  const middleware = authrimMiddleware(authrim);
  return middleware(c, next);
});

app.get('/api/profile', (c) => {
  const token = getAuth(c);
  return c.json({
    userId: token.claims.sub,
    scope: token.claims.scope,
  });
});

export default app;

Edge Runtime Initialization

On edge runtimes like Cloudflare Workers, consider caching the AuthrimServer instance at the module level or using Durable Objects to avoid repeated initialization. The SDK’s JWKS cache handles this efficiently, but minimizing init() calls improves latency.

HTTPS Requirement

By default, @authrim/server enforces HTTPS for all external URLs (issuer, JWKS endpoint, introspection, revocation). This prevents token leakage over unencrypted connections.

For local development, you can disable this check:

const authrim = new AuthrimServer({
  issuer: 'http://localhost:4000',
  audience: 'http://localhost:3000',
  requireHttps: false, // Only for local development!
});

Never Disable HTTPS in Production

Setting requireHttps: false in production exposes your application to man-in-the-middle attacks. Tokens and JWKS keys transmitted over HTTP can be intercepted and forged.

Multiple Issuers

If your resource server accepts tokens from multiple authorization servers, pass an array:

const authrim = new AuthrimServer({
  issuer: [
    'https://auth.example.com',
    'https://auth.partner.com',
  ],
  audience: 'https://api.example.com',
});

The SDK fetches and caches JWKS from all issuers during init().

Next Steps

• Security Considerations — Essential security guidance before going to production
• Token Validation — Detailed validation API and claims processing
• DPoP Validation — Validate sender-constrained tokens
• JWKS Management — Key caching, rotation, and custom cache providers
• Introspection & Revocation — Query and revoke tokens