Getting started
Installation
Requirements, install command, optional peer dependencies and the TypeScript settings that resolve the SDK's entry points.
Requirements
- Node.js 22 or later (
engines.nodeis>=22). - An ES module project. The package is
"type": "module"and every entry point is exported withtypesanddefaultconditions only: there is no CommonJS build. - A TypeScript
moduleResolutionthat honoursexports:NodeNext,Node16orBundler. - A CIRCLE auth-service instance and an application registered in it. See Register the application.
Install
pnpm add @circle-rd/auth-ai
npm install @circle-rd/auth-ai
See Release channels for how versions reach npm.
The SDK depends on jose, openid-client and zod, which npm installs for you.
Optional peer dependencies
Install only what the entry points you use need. Each one is an optional peer dependency, imported only from its own entry point.
| Entry point | Peer dependency | Range |
|---|---|---|
@circle-rd/auth-ai/fastify | fastify | >=5.12.6 |
@circle-rd/auth-ai/react | react | >=18 |
@circle-rd/auth-ai/vue | vue | >=3.4 |
Keep
fastify at 5.12.6 or later: several 2026 advisories are fixed there.Import paths
// Core: OIDC client, grants, AI clients, claims helpers, errors
import { createAuthClient, GrantManager, createAiClient } from "@circle-rd/auth-ai";
// Backend-for-frontend handlers and session store
import { createAuthHandlers, MemorySessionStore } from "@circle-rd/auth-ai/web";
// Fastify adapter
import { authPlugin, requireAuth, loadSession } from "@circle-rd/auth-ai/fastify";
// Bearer verification, back-channel logout, machine API
import { createBearerVerifier, createMachineApi } from "@circle-rd/auth-ai/server";
// Browser client and stores (no server code)
import { createBrowserAuth } from "@circle-rd/auth-ai/client";
// UI bindings
import { AuthProvider, useAuth } from "@circle-rd/auth-ai/react";
import { createAuthPlugin } from "@circle-rd/auth-ai/vue";
Importing from a path that is not in this list fails: the package's exports map exposes exactly these seven entry points. The full exports of each are in the Reference.
Next step
Register your application in auth-service, then follow the Quick start.