Quickstarts

Node quickstart

Verify OrthID sessions from any Node backend. Initialise the SDK with your secret key, verify a session token off an incoming request, and protect your API with middleware.

Use this guide for any server that receives requests from an OrthID-authenticated client: an Express or Fastify API, a worker, or an RPC handler. The job is always the same, take the session token off the request and verify it before doing work.

1. Install the SDK

The core SDK runs in any Node runtime.

Terminal

npm install @orthid/sdk

2. Initialise with your secret key

The SDK reads ORTHID_SECRET_KEY and ORTHID_REGION from the environment automatically. Importing orthid gives you a ready client; you can also construct one explicitly if you manage config yourself.

orthid.ts

import { orthid } from "@orthid/sdk";

// Reads ORTHID_SECRET_KEY and ORTHID_REGION from process.env.
// To configure explicitly instead:
//
// import { OrthID } from "@orthid/sdk";
// export const orthid = new OrthID({
//   secretKey: process.env.ORTHID_SECRET_KEY!,
//   region: "au-syd-1",
// });

export { orthid };

3. Verify a session token

Clients send the session token (a JWT) on the Authorization header as a bearer token. Pull it off the request and pass it to orthid.sessions.verify(). A successful call returns the session and the actor; a bad or expired token throws.

verify.ts

import { orthid } from "./orthid";

export async function verifyRequest(authHeader?: string) {
  const token = authHeader?.replace("Bearer ", "");
  if (!token) throw new Error("Missing token");

  const { session, actor } = await orthid.sessions.verify(token);

  // actor.type is "user" or "agent".
  // For agents, actor.actsFor holds the human on whose behalf it runs.
  return { session, actor };
}

Note

Verification is local: the SDK checks the JWT signature against your project’s published keys, plus expiry and region binding. There is no network call on the request path, so it is cheap to run on every request.

4. Protect an Express API

Wrap verification in middleware that attaches the actor to the request and returns 401 when the token is missing or invalid. Mount it ahead of any route that needs authentication.

requireAuth.ts

import type { Request, Response, NextFunction } from "express";
import { orthid } from "./orthid";

export async function requireAuth(
  req: Request,
  res: Response,
  next: NextFunction,
) {
  try {
    const token = req.headers.authorization?.replace("Bearer ", "");
    if (!token) {
      return res.status(401).json({ error: "Not authenticated" });
    }

    const { session, actor } = await orthid.sessions.verify(token);

    // Make the verified actor available to downstream handlers.
    res.locals.session = session;
    res.locals.actor = actor;
    next();
  } catch {
    res.status(401).json({ error: "Invalid session" });
  }
}

server.ts

import express from "express";
import { requireAuth } from "./requireAuth";

const app = express();

app.get("/me", requireAuth, (_req, res) => {
  res.json({ actor: res.locals.actor });
});

app.listen(3000);

Tip

Need to enforce roles or scopes as well as authentication? Read the actor’s scopes off the verified session and reject with 403 when they fall short. See RBAC & permissions.

Next steps

API reference for the full REST and gRPC surface behind the SDK.
Sessions to understand the token lifecycle you are verifying.
Scope an agent to issue short-lived, delegated credentials for AI workloads that call this API.