The Keycloak Admin API from TypeScript, without the surprises

说明与用途

Keycloak‑API‑TS 通过支持 CommonJS/ESM、将错误作为值返回、按调用选择 realm、自动刷新令牌以及完整的 100% API 覆盖率来消除官方 Keycloak 客户端的痛点，并提供类型安全。

问题

Automating Keycloak from Node.js hits friction points: ESM-only client, HTTP errors as exceptions, mutable global realm, token renewal issues, and incomplete API coverage.

结果

keycloak-api-ts eliminates ESM-only constraints, replaces exception‑based errors with discriminated unions, supports per‑call realm context, auto‑refreshes tokens, retries on 401, and offers full 100% API coverage with type safety.

工作流

• npm install keycloak-api-ts
• import KeycloakAPI from 'keycloak-api-ts'
• const api = new KeycloakAPI({baseUrl:'https://sso.example.com',credentials:{grantType:'client_credentials',clientId:'admin-service',clientSecret:process.env.KEYCLOAK_CLIENT_SECRET}})
• const created = await api.users.create('acme',{username:'jdoe',enabled:true})
• if (created.success) { console.log('new user id:',created.data) } else if (created.status===409) { console.log('user already exists') } else { console.error(created.status,created.error) }

证据

The package is "type": "module" with no CommonJS build.

来源

HTTP errors are thrown. A missing user (404) or a duplicate username (409) isn't exceptional; it's business logic.

来源

The default realm is global mutable state.

来源

Tokens renew only with a refresh token.

来源

By my count on 26.8.1, the official client covers about 340 of the 415 operations in the OpenAPI spec (≈82%).

来源

keycloak-api-ts ships both builds, so require and import work on any Node 20+, Jest in CommonJS mode included, without relying on require(esm).

来源

Errors as values. Every call resolves to { success, status, data | error }, a discriminated union.

来源