applica-iam-client

Python client for the Applica IAM service. Async-only, type-safe, mirroring the TypeScript @applica-software-guru/iam-client.

Installation

pip install applica-iam-client

Quick Start

import asyncio

from iam_client import create_iam_client


async def main():
    async with create_iam_client(api_url="https://server.com/api", api_key="your-system-api-key") as iam:
        await iam.auth.login({"username": "user@test.com", "password": "secret"})
        tenants = await iam.tenants.search({"keyword": "test"})
        user = await iam.users.get_by_id("user-id")
        await iam.roles.register({"code": "EDITOR", "name": "Editor", "permissions": ["read", "write"]})


asyncio.run(main())

Authentication

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

How authentication works in the client

When you set api_key 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/**:

iam = create_iam_client(api_url="https://server.com/api", api_key="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 — Application with logged-in user:

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

iam = create_iam_client(api_url="https://server.com/api")

await iam.auth.login({"username": "admin@test.com", "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 — Application that also needs tenant management:

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

iam = create_iam_client(api_url="https://server.com/api", api_key="your-system-api-key")

await iam.auth.login({"username": "admin@test.com", "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 code in production. It is intended for server-to-server communication, admin scripts, and development environments.

Architecture

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

Documentation

Scripts

pip install -e ".[dev]"    # Install in dev mode
ruff check src/            # Lint
pytest tests/ -v           # Run tests (requires IAM server)
python -m build            # Build package

License

MIT