Skip to content

First SDK script

This tutorial walks through the same scenario as First API call β€” listing users in your tenant β€” but using the AtmanID TypeScript SDK (AtmanIDClient). The SDK gives you typed responses, an automatic retry on server and network failures, structured error classes, and idiomatic resource accessors instead of raw URL strings.

Time estimate: ~15 minutes including SDK install + first script.

Prerequisites

  • Completed First API call (you already have an API key + understand the basics)
  • Node.js 18.17+ installed
  • A TypeScript project (or willingness to create one)

Step 1 β€” Install the SDK

The standalone npm package @atmanid/sdk is planned for v2 β€” until then, customers integrate via:

  1. Vendored source β€” pilot customers receive the SDK source and copy it into their project.
  2. Future npm package β€” npm install @atmanid/sdk once published. Track $ATMANID_BASE_URL/api/v1/changelog.json for the v2.0.0 announcement.

For this tutorial, we’ll assume you’ve vendored the SDK at ./vendor/atmanid-client/.

Step 2 β€” Instantiate the client

hello-atmanid.ts
import { AtmanIDClient } from './vendor/atmanid-client';
const client = new AtmanIDClient({
apiKey: process.env.ATMANID_API_KEY!,
baseUrl: process.env.ATMANID_BASE_URL, // your tenant's base URL β€” set it explicitly
// Optional config:
// timeoutMs: 8_000, // per-request timeout (default 8 s)
// userAgent: 'my-integration/1.0', // appended to the SDK's User-Agent
});

The constructor validates the API key format (atman_ prefix) before any network call β€” fails fast on misconfiguration. If you leave out baseUrl, the client targets AtmanID’s own hosted instance, not your tenant, so always pass it.

Step 3 β€” Make your first call

Same scenario as the curl tutorial β€” list users:

async function main() {
const result = await client.users.list({
page: 1,
limit: 25,
});
console.log(`Found ${result.total} users (page ${result.page} of ${result.total_pages}):\n`);
for (const user of result.data) {
console.log(` ${user.email.padEnd(40)} ${user.status.padEnd(15)} ${user.created_at}`);
}
}
main().catch(err => {
console.error('Request failed:', err);
process.exit(1);
});

Run it:

Terminal window
ATMANID_API_KEY="atman_your_key_here" ATMANID_BASE_URL="https://<your-atmanid-instance>" npx tsx hello-atmanid.ts

Expected output:

Found 48 users (page 1 of 2):
sarah.chen@example.com ACTIVE 2026-01-15T08:23:11.000Z
priya.singh@example.com ACTIVE 2026-02-03T16:30:15.000Z
taylor.brooks@auditor.example ACTIVE 2026-03-08T09:11:42.000Z
...

What the SDK gives you over raw HTTP

Three things show up immediately even in this minimal example:

1. Typed responses. result.data is User[], not unknown. Your IDE autocompletes user.email, user.status, etc. If the API contract changes (a field is renamed, a type narrows), TypeScript flags it at compile time β€” no runtime surprises.

2. Pagination shape is enforced. result.total_pages is always present (response shape). You don’t have to remember the field name or worry about typos.

3. Errors are structured classes. Instead of parsing raw HTTP, the SDK throws typed errors: AtmanIDClientError for any 4xx (with status, the machine-readable code and details), AtmanIDServerError for 5xx and AtmanIDNetworkError for timeouts and connection failures. All three extend AtmanIDError.

import { AtmanIDClientError } from './vendor/atmanid-client';
try {
const user = await client.users.get('00000000-0000-0000-0000-000000000000');
} catch (err) {
if (err instanceof AtmanIDClientError && err.code === 'UNAUTHENTICATED') {
console.error('API key invalid or expired:', err.message);
} else if (err instanceof AtmanIDClientError && err.status === 404) {
console.error('User not found β€” check the ID');
} else if (err instanceof AtmanIDClientError && err.code === 'RATE_LIMITED') {
console.error('Rate limited β€” back off and retry later');
} else {
throw err; // propagate unknown errors
}
}

Each error class carries err.requestId (from the X-Request-Id response header) for logging and support. See Common patterns for the full pattern.

Step 4 β€” Resource accessors

The SDK organizes endpoints into resource classes mirroring the REST surface:

// Users
await client.users.list({ page, limit });
await client.users.get(userId);
// Apps + entitlements
await client.apps.list();
await client.entitlements.list({ application_id });
await client.entitlements.get(entitlementId);
// Bundles (role packages)
await client.bundles.list();
await client.bundles.get(bundleId);
// JML lifecycle (every write takes an idempotency_key)
await client.jml.joiner({
idempotency_key: `hris-${employeeId}`,
email: 'new.hire@example.com', first_name: 'New', last_name: 'Hire',
});
await client.jml.status(`hris-${employeeId}`); // poll the event by its idempotency_key
// Audit
await client.audit.list({ since: '2026-05-01T00:00:00Z', until: '2026-05-10T00:00:00Z' });
// Agents (NHIs)
await client.agents.register({
idempotency_key: 'register-slack-release-bot',
name: 'slack-release-bot',
type: 'Service Account',
owner_team: 'platform',
owner_email: 'platform-eng@example.com',
purpose: 'Posts release notes to #releases',
});
// SoD
await client.sodViolations.list({ status: 'OPEN' });
// Webhooks
await client.webhooks.create({
url: 'https://your-app.com/atmanid-webhook',
events: ['ACCESS_APPROVED', 'ACCESS_REVOKED'],
});

Each call needs the matching scope on your API key (for example read:users, read:audit_logs, write:nhi, write:jml, write:webhooks). The SDK Reference lists the resource classes; the API Reference has every request and response field.

Common first-script errors

Symptom Cause Fix
Cannot find module './vendor/atmanid-client' The SDK isn’t where the import expects it Check the vendored folder path matches the import
Error: AtmanIDClient: apiKey is required and must start with "atman_" Key missing or doesn’t start with atman_ Verify env var β€” see Step 1 of First API call
TypeScript type errors on fields Stale SDK vendored vs current API Ask us for the current SDK source; check $ATMANID_BASE_URL/api/v1/changelog.json for breaking changes
AtmanIDNetworkError: Request timed out after 8000ms Network or service issue Check $ATMANID_BASE_URL/api/healthz; the SDK retries once on 5xx and network errors before throwing

Where to go next

  • Common patterns β€” pagination across multiple pages, error handling, retries, rate limit handling, webhook signature verification
  • SDK Reference β€” installation and the resource catalog
  • API Reference β€” the underlying REST surface the SDK wraps

Β© AtmanID Β· Privacy