Keycloak API Manager

keycloak-api-manager is a Node.js wrapper around the Keycloak Admin REST API. It provides a stable, function-oriented interface for managing Keycloak resources in code, scripts, and CI/CD pipelines.

What You Can Manage

• Realms
• Users
• Roles (realm/client/composite)
• Groups and group permissions
• Clients and client scopes
• Identity Providers
• Components
• Authentication flows and required actions
• Attack detection (brute force endpoints)
• Organizations (Keycloak 25+)
• User Profile config (Keycloak 15+)
• Client Policies and Profiles
• Server Info

Installation

npm install keycloak-api-manager

OIDC Deprecation Notice

DEPRECATION NOTICE (v6.0.0): The OIDC authentication methods (login(), loginPKCE(), generateAuthorizationUrl(), auth()) have been deprecated and moved to keycloak-express-middleware.

This package is now exclusively for Keycloak admin resource management. For user authentication flows, use keycloak-express-middleware instead.

See OIDC_MIGRATION_PLAN.md for migration details.

Quick Start

const KeycloakManager = require('keycloak-api-manager');

await KeycloakManager.configure({
  baseUrl: 'https://your-keycloak-host:8443',
  realmName: 'master',
  clientId: 'admin-cli',
  username: 'admin',
  password: 'admin',
  grantType: 'password',
  tokenLifeSpan: 60
});

// Alternative after configure(): update runtime context (for example realm)
// without re-authenticating or calling configure() again.
KeycloakManager.setConfig({ realmName: 'my-realm' });

const users = await KeycloakManager.users.find({ max: 20 });
console.log(users.length);

KeycloakManager.stop();

Keycloak Feature Flags

Some APIs exposed by this package depend on Keycloak server features that are disabled by default. Enable these flags when you want full endpoint coverage (local dev, CI, or production environments that use these modules):

--features=admin-fine-grained-authz:v1,organization,client-policies

What each flag is for:

• admin-fine-grained-authz:v1: enables management-permissions endpoints used by group/user fine-grained permission flows.
• organization: enables Organizations APIs.
• client-policies: enables Client Policies and Client Profiles APIs.

When you can skip them:

• If you only use core admin operations (for example realms/users/clients CRUD), the package still works without these flags.
• If you use organizations, clientPolicies, or management-permissions methods, these flags are required.

Why admin-fine-grained-authz:v1 in Keycloak 26.x

In Keycloak 26.x, the management-permissions APIs used by this package are compatible with the v1 variant, so admin-fine-grained-authz:v1 is the recommended setting.

Example (Docker)

docker run -d --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_FEATURES=admin-fine-grained-authz:v1,organization,client-policies \
  quay.io/keycloak/keycloak:latest start-dev

See Keycloak Setup and Feature Flags for full setup details.

Public API Entry Points

• configure(credentials)
• setConfig(overrides)
• getToken()
• stop()

Configured handler namespaces:

• realms
• users
• clients
• clientScopes
• identityProviders
• groups
• roles
• components
• authenticationManagement
• attackDetection
• organizations
• userProfile
• clientPolicies
• serverInfo

Documentation Map

All documentation is centralized under docs/.

Guides

• OIDC Migration Plan - Migration notes for legacy OIDC helpers

API Reference

• API Reference (Index)
• API - Configuration
• API - Realms
• API - Users
• API - Clients
• API - Client Scopes
• API - Groups
• API - Roles
• API - Identity Providers
• API - Components
• API - Authentication Management
• API - Attack Detection
• API - Organizations
• API - User Profile
• API - Client Policies
• API - Server Info

General Documentation

• Architecture and Runtime
• Keycloak Setup and Feature Flags
• Testing Guide — setup, configuration, commands, and test architecture
• Deployment (Local/Remote, HTTP/HTTPS)

Testing

npm run setup-keycloak
npm test

Or test workspace only:

npm --prefix test test

npm run setup-keycloak is an interactive helper that can start Keycloak via Docker Compose (local/remote, HTTP/HTTPS) and update the test baseUrl in config.

The suite runs against a real Keycloak instance and provisions a shared test realm during setup.

Repository Structure

Handlers/           # Keycloak resource wrappers
index.js            # Package runtime and handler wiring
index.mjs           # ESM bridge
test/
  specs/            # Test suites (core, diagnostics, matrix)
  support/          # Shared setup/bootstrap/config loaders
  config/           # default/local/secrets test configs
  docker-keycloak/  # Compose files and setup scripts
docs/               # Centralized documentation

Versioning and Compatibility

• Package version: 6.0.3
• Keycloak Admin client dependency: @keycloak/keycloak-admin-client
• Main compatibility target: Keycloak 25/26

Breaking Changes in v6.0.0

See OIDC Deprecation Notice.

License

MIT