@identia/sdk

TypeScript SDK for the Identia CIAM platform. Provides JWT parsing, access scope evaluation, feature flags, permissions, entitlements, and an API client for server-side and client-side use.

Installation

npm install @identia/sdk

Quick Start

import { IdentiaClient } from '@identia/sdk';

const client = new IdentiaClient({
  domain: 'your-tenant.accessiq.app',
  apiKey: 'your-sdk-api-key',
});

await client.init(accessToken);

// Check a feature flag
const enabled = client.isFeatureEnabled('new-dashboard');

// Check a permission
const canEdit = client.hasPermission('orders:edit');

// Check an entitlement
const hasModule = client.hasEntitlement('advanced-analytics');

Features

| Feature | Description | |---------|-------------| | Access Scope Parsing | Decode access_scope from Identia JWTs — organizations, roles, permissions in one claim | | Feature Flags | Evaluate tenant-scoped and org-scoped flags with real-time updates | | Permissions | Check role-based and direct permissions, including org-hierarchy inheritance | | Entitlements | Enforce plan-based entitlements and quota limits | | API Client | Typed HTTP client for Identia APIs with automatic token refresh | | Auth Flow | Server-side login orchestration — list providers, get authorization URL, exchange code for tokens | | Registration | Public API client for self-service signup and access requests | | Impersonation | DPoP-secured handoff code exchange for support impersonation flows | | Event System | Subscribe to SDK events (init, flag changes, errors) |

API Reference

IdentiaClient

const client = new IdentiaClient({
  domain: 'tenant.accessiq.app',
  apiKey: 'sdk-api-key',
});

await client.init(accessToken);

// Feature flags
client.isFeatureEnabled('feature-name');           // boolean
client.getFeatureFlag('feature-name');              // { enabled, variant, metadata }
client.getAllFeatureFlags();                         // Record<string, FeatureFlag>

// Permissions
client.hasPermission('resource:action');            // boolean
client.hasRole('admin');                            // boolean
client.getPermissions();                            // string[]

// Entitlements
client.hasEntitlement('module-name');               // boolean
client.getQuota('api-calls');                       // { limit, used, remaining }
client.getEntitlements();                           // EntitlementsData

// Organizations
client.getOrganizations();                          // AccessScopeOrgDetail[]
client.setCurrentOrganization(orgId);               // Switch org context

JWT Utilities

Parse the Identia access_scope claim without making API calls:

import { parseAccessScopeFromJwt, isAccessScopeTruncated } from '@identia/sdk';

const scope = parseAccessScopeFromJwt(accessToken);
// { organizations: [...], permissions: [...], roles: [...] }

if (isAccessScopeTruncated(accessToken)) {
  // JWT was too large — call the API for full scope
}

AuthClient

Server-side authentication flow via AccessIQ (SDK key with auth scope required):

import { AuthClient } from '@identia/sdk';

const auth = new AuthClient({
  gatewayUrl: 'https://identity.accessiq.app/api/v1',
  sdkKey: process.env.SDK_KEY,
});

// 1. List identity providers for login buttons
const providers = await auth.getProviders();
// [{ id, type: 'AZURE_ENTRA', name: 'Medline Entra ID', primary: true }]

// 2. Get authorization URL (server-side PKCE handled by AccessIQ)
const { authorizationUrl, state } = await auth.getAuthorizationUrl(
  providers[0].id,
  'https://myapp.com/api/auth/callback',
);

// 3. After IdP callback, exchange the code for AccessIQ tokens
const tokens = await auth.exchangeCode({
  providerId: providers[0].id,
  code: 'authorization-code-from-callback',
  state: state,
  redirectUri: 'https://myapp.com/api/auth/callback',
});
// { access_token, id_token, refresh_token, userId, user, tenantId, sessionClaims }

Registration Client

Public API for self-service signup (no auth required):

import { RegistrationClient } from '@identia/sdk';

const reg = new RegistrationClient({
  domain: 'tenant.accessiq.app',
});

// Submit a user access request
const result = await reg.submitUserAccessRequest({
  email: '[email protected]',
  firstName: 'Jane',
  lastName: 'Doe',
  organizationId: 'org-uuid',
});

Impersonation Handoff

import { exchangeHandoffCode, generateDPopProof } from '@identia/sdk';

const { accessToken, expiresIn, targetUser } = await exchangeHandoffCode({
  domain: 'tenant.accessiq.app',
  handoffCode: 'code-from-url',
  dpopProof: await generateDPopProof(privateKey, 'POST', tokenEndpoint),
});

Events

client.on('initialized', (payload) => { /* SDK ready */ });
client.on('flags_updated', (flags) => { /* real-time flag change */ });
client.on('error', (err) => { /* handle SDK error */ });

Related Packages

| Package | Description | |---------|-------------| | @identia/react | React hooks and guard components for the SDK | | @identia/auth-core | Framework-agnostic auth engine (OIDC, PKCE, passkeys) | | @identia/auth-react | React auth components (LoginPage, AuthGuard, useAuth) |

License

MIT