Understanding the Keycloak Admin API

If you’re managing user identities, roles, or secure login flows across multiple applications, you’ve likely come across Keycloak — an open-source identity and access management solution. While Keycloak’s web admin console is user-friendly, real power comes from its Admin REST API.

This article introduces the Keycloak Admin API, showing you what it is, why it matters, and how to use it to automate and scale identity management in your applications.

1. What is the Keycloak Admin API?

The Keycloak Admin API is a RESTful interface that lets you programmatically manage everything Keycloak offers:

• Realms
• Users
• Clients (applications)
• Roles
• Groups
• Authentication flows
• Sessions and tokens

In short, everything you can do in the Keycloak Admin Console can also be done via the API.

2. Why Use the Admin API?

You might use the Admin API if you need to:

• Sync users from an external system like LDAP or a custom user database
• Automate user creation or role assignment during CI/CD deployments
• Build a custom admin dashboard
• Manage Keycloak configuration across multiple environments (Dev/Test/Prod)

3. Authentication: Getting a Token

To use the Admin API, you need a Bearer token. You typically get this by logging in as an admin user under the master realm.

Example (with curl):

curl -X POST "http://localhost:8080/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin" \
  -d "password=admin_password" \
  -d "grant_type=password" \
  -d "client_id=admin-cli"

The response will include an access_token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Use this token in the Authorization header of subsequent requests:

-H "Authorization: Bearer <access_token>"

4. Common Use Cases and Endpoints

Here are some of the most common things you can do with the Keycloak Admin API:

🔍 1. List All Realms

http

GET /admin/realms

🔍 2. Get All Users in a Realm

GET /admin/realms/{realm}/users

curl -X GET "http://localhost:8080/admin/realms/myrealm/users" \
     -H "Authorization: Bearer $TOKEN"

🔍 3. Create a New User

POST /admin/realms/{realm}/users

Example payload:

{
  "username": "johndoe",
  "email": "john@example.com",
  "enabled": true,
  "firstName": "John",
  "lastName": "Doe"
}

🔍 4. Reset a User Password

PUT /admin/realms/{realm}/users/{id}/reset-password

Payload:

{
  "type": "password",
  "value": "new_secure_password",
  "temporary": false
}

🔍 5. Assign a Realm Role to a User

POST /admin/realms/{realm}/users/{id}/role-mappings/realm

Payload:

[
  {
    "id": "role-id",
    "name": "my-role"
  }
]

5. Using the Node.js SDK

If you’re building with JavaScript, you can use the @keycloak/keycloak-admin-client package:

npm install @keycloak/keycloak-admin-client

Example usage:

const KcAdminClient = require('@keycloak/keycloak-admin-client').default;

const kc = new KcAdminClient();

await kc.auth({
  username: 'admin',
  password: 'admin_password',
  grantType: 'password',
  clientId: 'admin-cli',
});

kc.setConfig({ realmName: 'myrealm' });
const users = await kc.users.find();
console.log(users);

What is a Realm?

A realm in Keycloak is an isolated unit for managing users, roles, clients, and policies. Each realm is completely independent — think of it like a tenant or project space.

• The default realm is master — used to manage Keycloak itself.
• You can create custom realms for each of your applications or customers.

To list all users across all realms, you must first get the list of realms, then fetch users per realm — there’s no global “all users” endpoint.

Access Control

To use the Admin API:

• Your user must have admin privileges in the target realm.
• Your client (usually admin-cli) must have proper roles (realm-admin, etc.).

✅ Conclusion

The Keycloak Admin API unlocks the full automation potential of Keycloak, allowing you to manage identity and access at scale, integrate with external systems, or build custom dashboards. Whether you’re writing shell scripts or using SDKs like Node.js or Python, the API offers all the power you need — programmatically.

📚 References

• Keycloak Admin REST API Docs
• Swagger UI (if enabled)
• Keycloak Admin Client (Node.js)