Keycloak 26.5.0 Questions about Account REST API usage and custom Account Console design

[Grant Yang]

Hello Keycloak Community,

I’m currently evaluating Keycloak 26.5.0 as the CIAM platform for my system and would like to ask for clarification regarding the Account functionality and APIs.

Background

• Keycloak is used as the central CIAM system for multiple applications (mobile apps and web apps).
• Each application requires access to user self-service account capabilities, such as:
  • updating profile information,
  • managing credentials,
  • reviewing active sessions,
  • managing consents.
• We plan to build and operate our own Account Console UI, independently deployed, to be shared by both app and web clients.

Questions

1. Existence and scope of Account REST API

We need to expose Account-related REST APIs to client applications while ensuring correct audit trails.

• Using the Admin REST API for end-user self-service operations causes audit records to be misleading, as actions are performed using service or admin credentials instead of the actual end user.
• We noticed that Keycloak exposes internal HTTP endpoints under paths such as /realms/{realm}/account/*, which are used by the built-in Account Console.
• However, in Keycloak 26.5.0 documentation, we cannot find an officially documented and supported Account REST API comparable to the Admin REST API.

Questions:

• Is there an officially supported Account REST API in Keycloak 26.5.0?
• Are the /account endpoints considered stable and intended for external consumption, or are they strictly internal to the built-in Account Console UI?

2. The purpose of the account-api feature flag

We experimented with enabling the account-api feature via configuration, but could not find clear documentation explaining:

• what functionality this feature enables,
• whether it exposes or stabilizes any REST endpoints,
• or how it is intended to be used in production.

Question:

• What is the intended purpose of the account-api feature in Keycloak 26.5.0?

3. Recommended architecture for a custom Account Console

Given the above constraints, we would like guidance on the recommended approach:

• If a custom Account Console UI is required,
  • should it directly call internal /account endpoints?
  • or is the recommended approach to implement a custom backend using SPI / extensions?
• How does the Keycloak team recommend handling:
  • end-user authorization,
  • audit correctness,
  • and long-term API stability for account self-service scenarios?

Summary

In short, we would appreciate clarification on:

2802. Whether a supported Account REST API exists in Keycloak 26.5.0.
2803. The exact role of the account-api feature.
2804. The recommended way to implement a custom Account Console while preserving security, audit accuracy, and upgrade safety.

Thank you very much for your time and for maintaining Keycloak.

Any pointers to documentation, design discussions, or community best practices would be greatly appreciated.

Best regards

[Mikkel Bernhof Jakobsen]

Hi Grant

We just went ahead and built a custom account UI for Keycloak using the existing account APIs.

Our approach was this:

• Instead of building a separately deployed account UI, we implemented a custom theme that includes a custom Vue UI that is deployed together with our Keycloak instance (a customized Keycloak docker image)
• This also gives us access to some useful existing features of Keycloak, such as internationalization (access to existing translations), referrer client information and more.
• Automated testing of our customized Keycloak image includes browser-based tests that help verify that a Keycloak upgrade doesn't break our custom account functionality.
• Since there is no documentation regarding account API at this point, we simply looked at how the built-in account UI uses the API. This isn't ideal (we'd prefer e.g. an OpenAPI spec) but it wasn't too difficult either.

I'd say that it's a lot of unnecessary overhead to implement your own account API unless you want to either add new functionality or restrict usage of built-in functionality. You mention audit handling yourself, which is just one example of complexity that you'll have to implement yourselves. However, if you DO implement your own, you should disable "account" and "account-api" features.

"account-api" feature simply represents the API that is used by the built-in account console. It's enabled by default.

You are not the first to request documentation of current account API, see e.g. https://github.com/keycloak/keycloak/issues/13203

Hope this helps

Mikkel B. Jakobsen

--
You received this message because you are subscribed to the Google Groups "Keycloak Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to keycloak-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/keycloak-dev/3c0dec21-d8ca-4183-92e9-a4702c07c257n%40googlegroups.com.