Skip to content

SDK Reference

The AtmanID TypeScript SDK (AtmanIDClient) is the recommended client for Node and TypeScript integrations. It wraps the v1 REST API with typed responses, a retry on transient failures, structured error classes, and IDE autocomplete on every method. Pilot customers vendor its source today; it will ship as the @atmanid/sdk npm package in v2.

Working alternatives (use these now)

Installation

The standalone @atmanid/sdk npm package is planned for v2. Until then, pilot customers receive the SDK source from us β€” dependency-free TypeScript you vendor into your project (for example at ./vendor/atmanid-client/). See First SDK script β†’ Setup for the exact steps.

Terminal window
# Planned for v2 (not yet published β€” vendor the client today, see above):
# npm install @atmanid/sdk

Quickstart

// Vendored SDK source (the @atmanid/sdk npm package is planned for v2)
import { AtmanIDClient } from './vendor/atmanid-client';
const client = new AtmanIDClient({
apiKey: process.env.ATMANID_API_KEY!,
// Your tenant's base URL, provided with your onboarding
baseUrl: process.env.ATMANID_BASE_URL,
});
// List the first page of users in your tenant (default limit 25)
const { data: users, total, total_pages } = await client.users.list();
console.log(`${users.length} of ${total} users (page 1 of ${total_pages})`);

Resource catalogs

The SDK exposes one method group per API resource class. Each maps 1:1 to the corresponding /api/v1/* endpoints documented in API Reference:

Resource group SDK methods Backing API
client.users .list() Β· .get(id) GET /api/v1/users[/{id}]
client.identities .list() GET /api/v1/identities
client.accessRequests .list() Β· .create(body) GET POST /api/v1/access-requests
client.apps .list() GET /api/v1/apps
client.entitlements .list() Β· .get(id) GET /api/v1/entitlements[/{id}]
client.bundles .list() Β· .create() Β· .get() Β· .update() Β· .delete() full CRUD on /api/v1/bundles
client.agents .list() Β· .register() Β· .update() Β· .deactivate() NHI lifecycle on /api/v1/agents
client.jml .joiner() Β· .mover() Β· .leaver() Β· .status() human JML on /api/v1/jml
client.audit .list() GET /api/v1/audit
client.sodViolations .list() GET /api/v1/sod-violations
client.webhooks .list() Β· .create() Β· .get() Β· .update() Β· .delete() Β· .test() /api/v1/webhooks
client.reachability .preview(body) POST /api/v1/reachability/preview
client.github .overview(params) Β· .discover(body) /api/v1/github/{overview,discover}

Not yet wrapped by the SDK β€” call them over HTTP: GET /api/v1/access-requests/{id}, GET /api/v1/users/{id}/entitlements, GET /api/v1/users/{id}/access-snapshot, and /api/v1/workflow-templates.

Typed error classes

The SDK throws one of four error classes β€” narrow with instanceof, then branch on code:

import {
AtmanIDClient,
AtmanIDError, // base class β€” every SDK error; carries .requestId
AtmanIDClientError, // 4xx β€” .status, .code (e.g. 'NOT_FOUND', 'RATE_LIMITED'), .details
AtmanIDServerError, // 5xx β€” .status (already retried once)
AtmanIDNetworkError, // timeout / DNS / connection failure (already retried once)
} from './vendor/atmanid-client';
try {
await client.users.get('00000000-0000-0000-0000-000000000000');
} catch (err) {
if (err instanceof AtmanIDClientError && err.status === 404) {
// Resource didn't exist
} else if (err instanceof AtmanIDClientError && err.code === 'RATE_LIMITED') {
// 429 is not retried by the SDK β€” back off and retry yourself
} else {
throw err;
}
}

The SDK retries once, after a short jittered delay, on 5xx responses and network errors. It never retries 4xx responses, including 429. The X-Request-Id of the most recent call is available as client.lastRequestId; on errors, read err.requestId.

See Common patterns β†’ Error handling for the full pattern catalog.

Source

The SDK source is shared with pilot customers today and will be published with the v2 @atmanid/sdk release. The documentation comment on every public method is the canonical reference until a generated reference page is published. Need a method signature that isn’t covered here? Email hello@atmanid.com and we’ll send the typed client directly.

Β© AtmanID Β· Privacy