@applica-software-guru/iam-client

TypeScript client for the Applica IAM service. Provides a centralized, framework-agnostic IamClient with dedicated services for each entity, plus a React Admin adapter.

| Info | Details | | ---------- | -------------------------------------------- | | Version | 5.0.* | | Author | Roberto Conte Rosito (Applica) | | Repository | https://bitbucket.org/applicaguru/iam-client | | License | MIT |

Installation

npm install @applica-software-guru/iam-client

Quick Start

import { createIamClient } from '@applica-software-guru/iam-client';

const iam = createIamClient({
  apiUrl: 'https://server.com/api',
  apiKey: 'your-system-api-key' // optional, see "Authentication" below
});

await iam.auth.login({ username: '[email protected]', password: 'secret' });
const tenants = await iam.tenants.search({ keyword: 'test' });
const { user } = await iam.users.getById('user-id');
await iam.roles.register({ code: 'EDITOR', name: 'Editor', permissions: ['read', 'write'] });

Authentication

The IAM backend uses three security chains with different authentication requirements:

| Endpoints | Auth required | Notes | | ------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------- | | /auth/** | None | Public endpoints (login, register, activate, recover) | | /tenants/** | System API key only | Requires x-api-key header matching the server's iam.api-key. Bearer tokens are not accepted. | | /users/**, /roles/**, /projects/**, /devices/** | Bearer token or API key | Any of these methods works: JWT from login, system API key, or tenant API key |

How authentication works in the client

When you set apiKey on the client, the x-api-key header is sent on every request. When a user is logged in, the Authorization: Bearer <token> header is also sent. The API key takes priority if both are present.

Scenario 1 — Server-side / admin scripts (no user login):

Use the system API key. This grants ROLE_SYSTEM and gives access to all endpoints including /tenants/**:

const iam = createIamClient({
  apiUrl: 'https://server.com/api',
  apiKey: 'your-system-api-key'
});

// No login needed — the API key authenticates all requests
await iam.tenants.register({ code: 'new-tenant', name: 'New Tenant' });
await iam.users.search({});
await iam.roles.register({ code: 'EDITOR', name: 'Editor' });

Scenario 2 — Browser app with logged-in user:

After login, the Bearer token authenticates requests to /users/**, /roles/**, /projects/**, /devices/**. No API key needed for these endpoints:

const iam = createIamClient({ apiUrl: 'https://server.com/api' });

await iam.auth.login({ username: '[email protected]', password: 'secret' });

// These work with the Bearer token from login
await iam.users.search({});
await iam.roles.register({ code: 'EDITOR', name: 'Editor' });
await iam.projects.search({});

// This will FAIL — /tenants/** requires the system API key, not a Bearer token
await iam.tenants.search({}); // ❌ 403

Scenario 3 — Browser app that also needs tenant management:

Provide both. The API key handles /tenants/**, the Bearer token handles everything else (or the API key handles everything):

const iam = createIamClient({
  apiUrl: 'https://server.com/api',
  apiKey: 'your-system-api-key'
});

await iam.auth.login({ username: '[email protected]', password: 'secret' });

// All endpoints work
await iam.tenants.search({});
await iam.users.search({});

What is the system API key and where to find it

The system API key is configured server-side in the IAM backend's application.yaml:

iam:
  api-key: 'your-secret-key-here'

This is the master key that grants ROLE_SYSTEM access. It is set by the server administrator and should be treated as a secret. The GodAuthenticationFilter on the backend reads the x-api-key header from incoming requests and compares it against this configured value.

There is no API endpoint to generate or rotate this key — it is a static configuration value managed at deployment time. To change it, update the iam.api-key property in the server configuration and restart the IAM service.

Important: The system API key gives unrestricted access to all endpoints. Never expose it in client-side browser code in production. It is intended for server-to-server communication, admin scripts, and development environments.

Tenant API keys

In addition to the system API key, each tenant can have its own API key (configured via setup.tenants[].api-key in application.yaml). A tenant API key authenticates requests to /users/**, /roles/**, /projects/**, /devices/** with the tenant's configured roles, but does not grant access to /tenants/**.

Architecture

IamClient
  ├── auth: AuthService          → /auth/*
  ├── users: UserService         → /users/*
  ├── tenants: TenantService     → /tenants/*
  ├── projects: ProjectService   → /projects/*
  ├── roles: RoleService         → /roles/*
  └── devices: DeviceService     → /devices/*

Documentation

| Topic | Description | | ----------------------------------------------------- | ------------------------------------------------- | | Getting Started | Installation, configuration, entry points | | Architecture | IamClient structure, HttpClient, project layout | | AuthService | Authentication, session, impersonation, PIN login | | UserService | User CRUD, roles, tenant/project assignment | | TenantService | Tenant CRUD (requires system API key) | | ProjectService | Project CRUD within tenants | | RoleService | Role and permission management | | DeviceService | Device management for PIN authentication | | Error Handling & Pagination | FailureResponse, error codes, pagination | | Storage | LocalStorage, MemoryStorage, custom IStorage | | React Admin | ApplicaAuthProvider, getClient() | | Type Reference | All TypeScript types and DTOs |

Scripts

npm run build     # Build with Vite
npm test          # Run tests with Vitest
npm run eslint    # Lint with ESLint
npm run format    # Format with Prettier

License

MIT