What is the Admin REST API?

Every action an administrator performs — creating a user, changing a client’s settings, adding a role — is, underneath the visual interface, a request sent to Keycloak’s Admin REST API, a structured set of web addresses (endpoints) that accept and return data in JSON format. The admin console you see in a browser is essentially a polished frontend built entirely on top of this same API. Nothing the console can do is impossible to do through the API directly; the console just makes it visual and clickable.

What is kcadm, then?

kcadm (short for “Keycloak Admin CLI,” and run as a script often called kcadm.sh on Linux/macOS or kcadm.bat on Windows) is a command-line tool, shipped alongside Keycloak, that wraps the Admin REST API in a much friendlier, typed-command form. Instead of manually constructing raw web requests, an administrator types a readable command like “get all users” or “create a new client,” and kcadm handles turning that into the correct underlying API call, sending it, and displaying the result.

Why does kcadm exist, when the admin console already works?

The admin console is excellent for one-off, exploratory tasks — looking around, making a single configuration change, checking on a specific user. But it doesn’t scale well to repetitive, bulk, or automated work. Creating five hundred test users one by one by clicking through forms is painfully slow; doing it with a short script calling kcadm in a loop takes seconds. kcadm exists specifically to make Keycloak administration scriptable — usable inside automation pipelines, setup scripts, and repeatable processes, not just interactive point-and-click sessions.

Key vocabulary, explained simply

graph TB
    U[Administrator] -->|types command| KC[kcadm CLI Tool]
    KC --> CFG[Local Config File
stores session/token]
    KC -->|constructs request| API[Admin REST API]
    API --> KCS[Keycloak Server]
    KCS -->|JSON response| API
    API -->|response| KC
    KC -->|formatted output| U
    

Component breakdown

How a typical session begins

Before running any administrative commands, an administrator first authenticates kcadm against a specific Keycloak server and realm, providing credentials once. kcadm exchanges these credentials for an access token behind the scenes and stores the resulting session information in its local configuration file. Every subsequent command in that session reuses this stored token automatically, refreshing it as needed, without requiring the administrator to log in again for each individual action.

Why does kcadm need its own configuration file?

Without some form of session persistence, every single kcadm command would need to include full authentication credentials, which would be both cumbersome to type repeatedly and a security risk if credentials ended up scattered across many command lines or scripts. The local configuration file’s session-based approach mirrors how the admin console itself keeps you logged in across multiple actions, just adapted to a command-line, scriptable context.

Authentication under the hood

When an administrator runs kcadm’s login command, providing a username, password, server URL, and realm, kcadm sends these credentials to Keycloak’s token endpoint, following the exact same OpenID Connect flow any other client application would use to obtain an access token. The resulting token, along with a refresh token, is saved into the local configuration file. From that point forward, every kcadm command attaches this access token to its outgoing API requests, and transparently uses the refresh token to obtain a new access token once the current one expires.

What happens when you run a command

When an administrator types a kcadm command — say, creating a new user — kcadm first parses the command’s structure: the action (create), the resource type (users), and any provided data (a JSON payload describing the new user, or individual field flags). It then constructs the exact corresponding HTTP request the Admin REST API expects, attaches the current access token for authentication, and sends the request to the Keycloak server. The server processes this exactly as it would any other API call — validating the token, checking the requester’s permissions, and performing the requested action — before returning a JSON response that kcadm then displays back to the administrator.

Permissions work exactly the same as anywhere else

Because kcadm ultimately authenticates as a real Keycloak user or service account and calls the same Admin REST API, it is bound by exactly the same role-based permission checks as any other caller. An account without sufficient administrative privileges will be rejected by the API in precisely the same way whether the request came from kcadm, the admin console, or a custom script calling the API directly. kcadm carries no special elevated access of its own.

Step-by-step: from typed command to completed action

sequenceDiagram
    participant Admin
    participant kcadm
    participant Config as Local Config File
    participant API as Admin REST API
    participant Server as Keycloak Server

    Admin->>kcadm: kcadm config credentials (login)
    kcadm->>Server: Requests access token
    Server-->>kcadm: Returns access + refresh token
    kcadm->>Config: Stores tokens locally
    Admin->>kcadm: kcadm create users -r myrealm -s username=jane
    kcadm->>Config: Reads stored access token
    kcadm->>API: POST /admin/realms/myrealm/users
    API->>Server: Validates token, checks permissions
    Server-->>API: Creates user, returns result
    API-->>kcadm: JSON response
    kcadm-->>Admin: Prints result to terminal
    

Notice that after the initial login, every subsequent command reuses the same stored token rather than re-authenticating from scratch — this is exactly what makes kcadm practical for scripting a whole sequence of administrative actions in one automated run, without needing to embed a password in every individual step.

The lifecycle of a kcadm session

Credential handling in scripts and automation

A common and risky pattern is embedding an administrator’s actual username and password directly inside an automation script that calls kcadm. If that script is ever shared, committed to version control, or exposed, those credentials are compromised along with it. A safer approach uses a dedicated service account with only the specific permissions the automation actually needs, rather than a full administrator’s personal credentials.

Protecting the local configuration file

Since kcadm’s local configuration file holds live session tokens, treating it with the same care as any other credential file matters — restricting its file permissions, avoiding storing it in shared or version-controlled locations, and ensuring automated systems clean up or isolate their session files appropriately between runs.

Auditability of kcadm actions

Because kcadm calls the same Admin REST API as the console, actions performed through it are captured by Keycloak’s admin event logging in exactly the same way — meaning a well-configured event listener or audit log will show kcadm-driven changes with the same detail as console-driven ones, an important property for maintaining a complete audit trail regardless of which interface an administrator used.

Proven patterns

Anti-patterns to avoid

Best practices

Common mistakes