Authio docs

Install

pnpm add @authio/node

Top-level shape

import { Authio, AuthioError } from "@authio/node";

const authio = new Authio({
  apiKey: process.env.AUTHIO_SECRET_KEY!,        // required
  apiUrl: "https://api.authio.com",             // optional; defaults to prod
  jwtIssuer: "https://api.authio.com",          // optional
  jwtAudience: "authio",                         // optional
});

authio.users          // get / list memberships
authio.organizations  // list / create / get
authio.memberships    // listForOrganization / add / remove
authio.sessions       // verify / switchOrg / revoke

Session verification

sessions.verify takes the access JWT and returns a typed session or null. JWKS is fetched once and cached internally; you can spawn multiple Authio instances per process without thrashing.

const session = await authio.sessions.verify(req.cookies.authio_session);
if (!session) return new Response("Unauthorized", { status: 401 });

session.userId    // always set
session.orgId     // null when user has multiple orgs and hasn't selected
session.role      // null when no org selected
session.expiresAt // ISO timestamp

Management API

// Organizations
const orgs = await authio.organizations.list();
const acme = await authio.organizations.create({ name: "Acme", slug: "acme" });

// Memberships (multi-org)
await authio.memberships.add(acme.id, { userId: "user_01H...", role: "admin" });
const members = await authio.memberships.listForOrganization(acme.id);
await authio.memberships.remove(acme.id, "mem_01H...");

// Cross-org listing for a single user
const all = await authio.users.listMemberships("user_01H...");
// returns the user's memberships across every org they belong to

Error handling

try {
  await authio.organizations.create({ name: "Acme", slug: "acme" });
} catch (err) {
  if (err instanceof AuthioError) {
    // err.code, err.status, err.requestId
  }
  throw err;
}

Custom fetch

Override the underlying fetch (e.g. inject tracing headers) by passing your own. The SDK will use whatever you pass; falling back to globalThis.fetch otherwise.

new Authio({
  apiKey: process.env.AUTHIO_SECRET_KEY!,
  fetch: tracingFetch,
});