Node.js SDK

@authdog/node-sdk 0.2.0 is the official Node.js client for the Authdog REST API. It lives in `node/` of authdog/sdk. It is a management and userinfo client, not a web-framework session binding.

The public npm registry does not host this package. Need to protect an Express, Fastify, Hono, or Koa route? Use a backend SDK.

Install

Clone the monorepo and build the package:

git clone https://github.com/authdog/sdk.git
cd sdk/node
pnpm install
pnpm build

The package is ESM and ships TypeScript types from dist/. Depend on that build from your app (a file: dependency, or your own registry). npm install @authdog/node-sdk does not resolve on the public registry.

Configure

Construct one client with the public API base URL. Pass a management Bearer credential (ad_…) when you call privileged endpoints:

import { AuthdogClient } from "@authdog/node-sdk"

const client = new AuthdogClient({
  baseUrl: "https://api.authdog.com",
  apiKey: process.env.AUTHDOG_API_TOKEN,
})

Keep the token server-side. getUserInfo still uses the caller access token, not the management key.

Optional config fields environmentSecret (adenv_), scimToken (adscim_), and hrisToken (adhris_) are the AuthZEN/MCP runtime, SCIM, and HRIS Bearers. timeout is milliseconds and defaults to 10000.

health() is public and works without an API key:

const probe = await client.health()

Call client.close() when the process is done with the client.

Resolve a user from an access token

import { APIError, AuthenticationError, AuthdogClient } from "@authdog/node-sdk"

const client = new AuthdogClient({ baseUrl: "https://api.authdog.com" })

try {
  const info = await client.getUserInfo(accessToken)
  console.log(info.user.displayName)
  console.log(info.user.emails[0]?.value)
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401: missing, invalid, or expired access token
    throw error
  }
  if (error instanceof APIError) {
    // transport or non-401 HTTP failure
    throw error
  }
  throw error
}

GET /v1/userinfo always sends Authorization: Bearer <access-token>. A constructor API key does not replace that header.

UserInfoResponse uses camelCase fields (user.displayName, session.remainingSeconds).

Call the management API

Namespaces on the client wrap Waves 1–5 of the public /v1 surface:

const orgs = await client.organizations.list()
const users = await client.users.list("ten_123", "env_456")

Directory calls take the tenant id, then the environment id. AuthZEN discovery is unauthenticated. Evaluate, search, and the MCP runtime use environmentSecret. SCIM uses scimToken. HRIS uses hrisToken. OpenAPI at `/v1/openapi` is the field-level contract.

Errors

Other languages

Next

• API reference: auth, versioning, and resource families
• Backend requests: validate sessions on incoming requests
• Users: directory model the users namespace talks to