Before diving into endpoints and tokens, it helps to understand what a REST API is in general, and why an identity platform like Keycloak needs one specifically for administration.

What is a REST API?

A REST API is a standardized way for one piece of software to ask another piece of software to do something, or to fetch information from it, over the network, using simple, predictable web requests. Instead of a human clicking a button labeled “Create User” in a web page, a piece of code sends a structured request that says, in effect, the exact same thing — “create a user with these details” — and receives a structured response back describing what happened.

What is the Admin REST API, specifically?

Keycloak’s Admin REST API is the complete collection of these programmatic endpoints covering every administrative capability the platform offers — realms, users, groups, roles, clients, identity providers, authentication flows, and far more. Crucially, this is not a limited, secondary interface bolted on for convenience. Keycloak’s own web-based admin console is itself built as a client of this exact same API, meaning nothing an administrator can do by clicking through the console is fundamentally unavailable to a well-written script or automated tool calling the API directly.

Why an administrative API matters beyond convenience

Manually clicking through a web console does not scale well once an organization needs to create hundreds of realms for different customers, provision thousands of users during a migration, or keep identity configuration perfectly synchronized across multiple environments. The Admin REST API turns these repetitive, error-prone manual tasks into scripts and automated pipelines that can run reliably, consistently, and at whatever scale the organization actually needs.

The Admin REST API is organized around a clear, consistent structure, once you understand the small number of building blocks it is composed from.

Organized by realm, then by resource

Nearly every endpoint in the Admin REST API is scoped to a specific realm first, and then to a specific type of resource within that realm — users, clients, roles, groups, identity providers, and so on. This mirrors exactly how the admin console itself is organized, since, as already noted, the console is simply a visual front end for these same underlying, realm-scoped resource endpoints.

Authentication via bearer tokens

Every call to the Admin REST API must include a valid access token, presented as what is called a bearer token, in the request. Keycloak checks this token to determine who is making the request and what that identity is actually authorized to do, before processing anything. There is no separate, weaker authentication path for the API — it relies on exactly the same token-based security model Keycloak uses to protect every other application it secures.

The special “master” realm and admin-cli client

Keycloak ships with a special realm, typically named master, intended specifically for platform-wide administration, along with a pre-configured client commonly called admin-cli, designed to make obtaining an initial administrative token straightforward for scripts and command-line tools. Many automation setups authenticate against this realm and client first, in order to obtain the token subsequently used for calls against other realms.

Service accounts for machine-to-machine automation

Rather than relying on a human administrator’s own personal credentials inside an automated script, Keycloak supports service accounts — a special kind of client-associated identity, with its own assigned roles and permissions, specifically designed for machine-to-machine use. A well-designed automation pipeline typically authenticates as a dedicated service account, rather than impersonating a real administrator’s personal login.

flowchart TD
    A["Automation Script or Tool"] --> B["Authenticate as a Service Account"]
    B --> C["Keycloak issues an Access Token with admin-relevant roles"]
    C --> D["Script calls Admin REST API endpoint"]
    D --> E["Keycloak validates the bearer token"]
    E --> F["Keycloak checks assigned roles/permissions for this action"]
    F -->|"Authorized"| G["Requested change is applied: realm, user, client, role..."]
    F -->|"Not authorized"| H["Request rejected"]
    I["Admin Console (a browser-based client)"] --> D
    

Notice that the admin console feeds into the exact same request-and-authorization pipeline as any external automation. This shared path is precisely why understanding the Admin REST API also deepens your understanding of how Keycloak’s own administrative security model works end to end.

This chapter walks through exactly what happens, step by step, when a script or tool calls the Admin REST API to make a change.

Step one: obtaining a token

Before any administrative action can be requested, the calling script must first authenticate against Keycloak’s own token endpoint, presenting valid credentials — typically a service account’s client identifier and secret — and receiving back a signed access token in return. This step is identical in principle to how any application obtains a token for a regular user login, just performed on behalf of an automated identity rather than a human.

Step two: presenting the token on every request

Once obtained, this token must be included on every subsequent call to the Admin REST API, presented as a bearer token in the request. Keycloak checks the token’s signature and expiry on each call, exactly as it would for a token protecting any other application, since the Admin REST API is, from a security standpoint, simply another protected resource sitting behind the same authentication model.

Step three: authorization checks per action

Holding a valid token is not, by itself, enough to perform every possible action. Keycloak separately checks whether the specific identity behind that token has actually been granted the roles or permissions required for the specific action being requested — creating a user is a different permission from deleting a realm, and a token valid for one action is not automatically valid for every other administrative action across the entire platform.

Step four: the request is processed and a response returned

Once both the token itself and the specific authorization for the requested action check out, Keycloak processes the request — creating, updating, deleting, or retrieving whichever resource was targeted — and returns a structured response describing the outcome, whether that is the newly created resource’s details, a confirmation of success, or a clear description of why the request failed.

Fine-grained admin permissions

Beyond simple realm-wide administrator roles, Keycloak supports more finely scoped administrative permissions, allowing an identity to be granted rights over only a specific subset of resources — for example, permission to manage users within one particular group, rather than blanket administrative control over the entire realm. This lets automation and delegated administrators be granted precisely the access their specific job requires, rather than defaulting to broad, all-encompassing administrative rights out of convenience.

Following a single, realistic automation task — provisioning a new customer realm — end to end shows exactly how these pieces come together in sequence.

Automating administration through the Admin REST API is a genuine trade-off between speed and consistency on one hand, and increased operational and security responsibility on the other.

Where the balance typically lands

For organizations managing more than a handful of realms, clients, or users, the consistency and scalability benefits of API-driven administration almost always outweigh the added operational discipline required to secure and maintain it properly. The real work is in taking that operational discipline seriously — treating automation credentials, scoped permissions, and change review with the same rigor as any other critical piece of production infrastructure.

Because the Admin REST API can configure literally every aspect of an identity platform, it represents one of the highest-value targets an attacker could ever hope to reach.

Protecting service account credentials

A leaked service account credential with broad administrative permissions is, functionally, equivalent to handing an attacker full control over the identity platform itself — the ability to create administrative users, alter security policies, or extract sensitive configuration. Service account secrets deserve storage and handling at least as careful as any other highly privileged credential, such as a database root password.

Scoping permissions narrowly

Rather than granting every automation identity full, realm-wide administrative rights out of convenience, well-secured deployments use Keycloak’s fine-grained admin permissions to grant each service account only the specific rights its actual job genuinely requires — a pipeline that only ever provisions new users should not also hold the ability to delete entire realms.

Network exposure of the Admin REST API

Because this API can configure the entire identity platform, many organizations deliberately restrict network-level access to it — for example, allowing it to be reached only from trusted internal networks or specific automation infrastructure, rather than being reachable from the open internet in the same way a public login endpoint might be.

Rotating and expiring automation credentials

Just as short-lived tokens limit the damage of a leaked login credential elsewhere in Keycloak, automation credentials used to call the Admin REST API benefit from periodic rotation, and from being revoked promptly whenever a specific pipeline, tool, or integration is decommissioned, rather than left active indefinitely simply because no one remembered to remove it.

Given how much power the Admin REST API carries, visibility into exactly who is calling it, and what they are changing, is essential rather than optional.

The built-in admin events log

Keycloak maintains a dedicated admin events log, separate from its regular authentication events, specifically recording administrative actions — who made a change, what resource was affected, and what the change actually was. This log exists precisely because administrative changes carry outsized consequences compared to ordinary login activity, and deserve their own dedicated audit trail.

What to watch for in admin activity

A sudden burst of realm or client creation activity outside of an expected automation window, changes to security-sensitive settings like authentication flows or identity provider trust configuration, or administrative actions originating from an unfamiliar service account are all patterns worth specific attention, since each could indicate either a misconfigured pipeline or a genuine security incident in progress.

Exporting admin events for long-term retention

As with regular authentication events, Keycloak’s built-in admin event storage is not intended as a permanent archive. Forwarding admin events to an external logging or security monitoring system allows an organization to retain a long-term, searchable audit trail of every administrative change ever made, which is often specifically required for compliance and incident-investigation purposes.

Correlating API activity with deployment pipelines

For organizations managing identity configuration as code, correlating admin event log entries with the specific automated pipeline run that triggered them provides valuable end-to-end traceability, making it straightforward to answer, months later, exactly which deployment or script was responsible for any particular configuration change.

Organizations that lean heavily on the Admin REST API for real infrastructure management tend to converge on a small number of recognizable patterns.

Pattern: Identity configuration as code

Mature deployments treat realms, clients, and roles as declarative configuration, stored in version control and applied through automated tooling that calls the Admin REST API, rather than as one-off manual changes made directly through the console — giving them the same review, rollback, and audit benefits that infrastructure-as-code practices provide elsewhere.

Pattern: Dedicated, narrowly scoped service accounts per pipeline

Rather than sharing one broadly privileged automation credential across every pipeline and integration, well-organized deployments create a distinct service account for each specific automation purpose, each scoped only to the permissions that particular pipeline genuinely needs, limiting the blast radius if any single credential is ever compromised.

Anti-pattern: Sharing one master-realm admin credential everywhere

A common and risky shortcut is reusing a single, broadly privileged master-realm administrator credential across every automation script, integration, and manual troubleshooting task an organization has, rather than issuing distinct, appropriately scoped service accounts for each purpose.

A short list of disciplined habits consistently separates organizations that use the Admin REST API safely and effectively from those that eventually regret how loosely it was set up.

The Admin REST API becomes indispensable exactly at the point where an organization’s identity management needs outgrow what manual, one-at-a-time console clicks can reasonably support.

Multi-tenant SaaS provisioning

Software-as-a-service platforms onboarding new customer organizations at scale commonly automate the entire realm-creation process — new realm, initial clients, default roles, first administrative user — entirely through the Admin REST API, allowing new customers to be provisioned in seconds rather than requiring manual setup for every single signup.

Infrastructure-as-code identity management

Organizations that manage their broader infrastructure declaratively, through tools that describe desired configuration as code, frequently extend that same discipline to their Keycloak realms, clients, and roles, applying changes through the Admin REST API as part of the same automated, version-controlled deployment pipeline used for the rest of their infrastructure.

Large-scale user migrations

Organizations migrating tens of thousands of user accounts from a legacy identity system into Keycloak typically write scripts that call the Admin REST API’s user-creation and credential-management endpoints in bulk, since manually recreating even a small fraction of that many accounts through the console would be entirely impractical.

Internal developer self-service platforms

Some engineering organizations build an internal, self-service tool that lets development teams request and provision their own Keycloak clients for new applications, with the tool itself calling the Admin REST API behind the scenes under a tightly scoped service account, giving developers speed and autonomy without handing every team broad, direct administrative access to Keycloak itself.

The Admin REST API is not a secondary or lesser way of managing Keycloak — it is the same engine that powers the admin console itself, exposed directly for scripts, pipelines, and automated tools to use. This makes it an enormously powerful tool for consistency and scale, letting organizations manage realms, users, clients, and roles as reliably as any other piece of well-governed infrastructure. But that same power means every credential capable of calling it, every permission granted to those credentials, and every action taken through it deserves the same seriousness given to any other highly privileged part of the system. Used carelessly, it can turn a single leaked secret into sweeping, platform-wide compromise. Used deliberately, it becomes one of the most valuable tools an identity team has.