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.
# Planned for v2 (not yet published β vendor the client today, see above):# npm install @atmanid/sdkQuickstart
// 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