# 🔑 ACKC: API Client for Keycloak
[](https://pypi.org/project/ackc/)
[](https://pypi.org/project/ackc/)
[](https://github.com/acie-io/ackc/releases)
[](https://pypistats.org/packages/ackc)
[](https://deepwiki.com/acie-io/ackc)
[//]: # ([](https://deepwiki.com/acie-io/ackc))
A comprehensive Python client library for Keycloak Admin REST API, providing a clean and typed interface for managing Keycloak resources.
The only dependencies are `niquests` for HTTP and `attrs` for data models, making it lightweight and easy to integrate.
## Overview
ACKC is a fully-typed Python library that wraps Keycloak's Admin REST API.
It provides both synchronous and asynchronous interfaces for all major Keycloak administrative operations, with a focus on developer experience, type safety, and efficiency.
The author of this package was also a little fed up with the usual daily slog of CLI login and token acquisition before getting to work, so this library aims to make that process as painless as possible.
## Features
- **Complete API Coverage**: 100% implementation of all 371 non-deprecated Keycloak Admin API endpoints
- **Type Safety**: Full type annotations with `attrs` models for all requests and responses
- **Async Support**: Both sync and async methods for all operations (using the `niquests` library)
- **Auto-generated Models**: Generated from Keycloak's OpenAPI specification using `openapi-python-client`
- **CLI Tools**: Handy command-line utilities for common tasks like token acquisition and realm export
- **Developer Friendly**: Clean API design with explicit parameters and comprehensive docstrings
- **Multiple Auth Methods**: Support for client credentials, password grant, and device code flows
## Installation
`uv` is recommended, but you can also use other package managers like `pip`.
```bash
uv add ackc
```
Standalone tool installation is also available:
```bash
uv tool install --python 3.13 ackc
```
## Quick Start
```python
from ackc import KeycloakClient
client = KeycloakClient(
server_url="https://keycloak.example.com",
client_id="admin-cli",
client_secret="your-secret",
realm="my-realm", # Default realm for API calls
auth_realm="master", # Default realm for client authentication
)
with client:
users = client.users.get_all()
realms = client.realms.get_all()
async def main():
async with client:
await client.users.aget_all()
await client.realms.aget_all()
```
## Authentication Methods
ACKC supports multiple authentication flows:
### Client Credentials (Default, Recommended for M2M)
```python
client = KeycloakClient(
server_url="https://keycloak.example.com",
client_id="admin-cli",
client_secret="secret"
)
users = client.users.get_all()
```
### Password Grant (Legacy Flow)
```python
client = KeycloakClient(
server_url="https://keycloak.example.com",
client_id="my-client",
client_secret="secret"
)
token = client.get_token_password(
username="admin",
password="admin",
scopes=["openid", "profile", "email"]
)
```
### Device Code Flow (For CLI Tools)
```python
client = KeycloakClient(
server_url="https://keycloak.example.com",
client_id="cli-client"
)
def device_callback(*, verification_uri, user_code, expires_in):
print(f"Please visit: {verification_uri}")
print(f"User code: {user_code}")
print(f"You have {expires_in} seconds to authorize")
token = client.get_token_device(
scopes=["openid", "offline_access"],
callback=device_callback
)
```
### Working with JWTs
ACKC provides methods for validating and working with JWTs:
```python
claims = KeycloakClient.jwt_decode(jwt="your-jwt-token")
print(f"User: {claims.get('preferred_username')}")
print(f"Expires: {claims.get('exp')}")
needs_refresh = KeycloakClient.jwt_needs_refresh(jwt="your-jwt-token", buffer_seconds=300)
client = KeycloakClient(...)
user_info = client.jwt_userinfo(jwt="your-jwt-token")
token_info = client.jwt_introspect(jwt="your-jwt-token")
if token_info.get("active"):
print(f"Token is valid for user: {token_info.get('username')}")
new_token = client.jwt_refresh(refresh_token="your-refresh-token")
```
## Async Support
All API methods have async equivalents with the `a` prefix, allowing for non-blocking operations:
```python
import asyncio
from ackc import KeycloakClient
async def main():
client = KeycloakClient(
server_url="https://keycloak.example.com",
client_id="admin-cli",
client_secret="secret"
)
async with client:
users = await client.users.aget_all()
realms = await client.realms.aget_all()
roles = await client.roles.aget_all()
asyncio.run(main())
```
## CLI Tools
ACKC includes helpful CLI tools:
### Get Token
Acquire an access token for Keycloak using client, password, or device code flows.
Also supports 2FA for password grant using the `--otp`/`--otp-code` options.
```bash
auth-token --server https://keycloak.example.com --client admin-cli
```
### Export Realm
Export a realm and associated data to JSON.
```bash
auth-realm-export my-realm
```
### Management Commands
Get health status or dump Keycloak prometheus metrics.
Requires `KC_HEALTH_ENABLED` or `KC_METRICS_ENABLED` to be set in Keycloak.
```bash
auth-mc --url http://localhost:9000 --json metrics
```
### Initialize Docker Environment
Creates Keycloak Docker compose.yaml and .env files in the current directory for development.
```bash
ackc-init
```
## Advanced Usage
### Cloudflare Access Integration
```python
# Use with Cloudflare Access (+ Tunnel = HTTPS for local development or secure remote management)
# Note: This gets you past Cloudflare, but you still need to authenticate with Keycloak.
client = KeycloakClient(
server_url="https://keycloak.example.com",
cf_client_id='<your-cf-client-id>.access', # or CF_ACCESS_CLIENT_ID
cf_client_secret='your-cf-secret', # or CF_ACCESS_CLIENT_SECRET
)
```
### Per-Request Realm and Auth Realm Override
```python
# Initialize client for custom realm
client = KeycloakClient(server_url="...", realm="my-realm")
# Override realm for specific calls
users = client.users.get_all(realm="other-realm")
# Use a different realm for API client authentication (master by default).
# Recommended for backend production clients to maintain least privilege - the admin client should not have access to all realms.
company_realm = "my-company-realm"
client = KeycloakClient(server_url="...", auth_realm=company_realm, realm=company_realm)
```
### Direct API Access
(Just don't do this)
## Error Handling
```python
from ackc import KeycloakClient, AuthError
try:
with KeycloakClient(...) as client:
users = client.users.get_all()
except AuthError as e:
print(f"Authentication failed: {e}")
except Exception as e:
print(f"API error: {e}")
```
## Development
### Regenerating API Client
To update the generated code when Keycloak API changes:
```bash
python gen/generate_client.py --download
```
## Requirements
- Python 3.13+
- Keycloak 26+ (tested with Keycloak 26.3)
## License
This project is licensed under the Apache License 2.0. See the [license](license.md) file for details.
## Contributing
Contributions are welcome! Please read the [contributing guidelines](contributing.md) for details on how to contribute to this project.
## See Also
- [Keycloak Documentation](https://www.keycloak.org/documentation)
- [Keycloak Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/)
## Appearances
- [@thomasdarimont/awesome-keycloak](https://github.com/thomasdarimont/awesome-keycloak) (pending)
# API Modules
ACKC organizes Keycloak's functionality into logical API modules:
## Users API (`client.users`)
Manage users, credentials, roles, and user sessions.
- Create, read, update, delete users
- Manage user credentials and password resets
- User role mappings and group memberships
- User sessions and consent management
[Keycloak Documentation: User Management](https://www.keycloak.org/docs/latest/server_admin/#assembly-managing-users_server_administration_guide)
## Realms API (`client.realms`)
Configure realms, realm settings, and realm-level operations.
- Create and configure realms
- Manage realm settings and themes
- Default groups and client scopes
- Realm events and admin events
- Localization and internationalization
[Keycloak Documentation: Realms](https://www.keycloak.org/docs/latest/server_admin/#_configuring-realms)
## Clients API (`client.clients`)
Manage OAuth2/OIDC clients and their configurations.
- Create and configure clients
- Client secrets and registration tokens
- Client scopes and protocol mappers
- Service accounts and permissions
- Client session management
[Keycloak Documentation: Clients](https://www.keycloak.org/docs/latest/server_admin/#_oidc_clients)
## Roles API (`client.roles`)
Define and manage realm and client roles.
- Create realm and client roles
- Role hierarchies and composites
- Role permissions and attributes
- List role members
[Keycloak Documentation: Roles](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-realm-roles_server_administration_guide)
## Groups API (`client.groups`)
Organize users into groups with hierarchical structures.
- Create and manage groups
- Group hierarchies and subgroups
- Group role mappings
- Group members management
[Keycloak Documentation: Groups](https://www.keycloak.org/docs/latest/server_admin/#proc-managing-groups_server_administration_guide)
## Identity Providers API (`client.identity_providers`)
Configure external identity providers for federation.
- SAML and OIDC provider configuration
- Social login providers (Google, GitHub, etc.)
- Identity provider mappers
- First broker login flows
[Keycloak Documentation: Identity Providers](https://www.keycloak.org/docs/latest/server_admin/#_identity_broker)
## Authentication API (`client.authentication`)
Customize authentication flows and requirements.
- Authentication flows and executions
- Required actions configuration
- Authenticator providers
- Password policies
[Keycloak Documentation: Authentication](https://www.keycloak.org/docs/latest/server_admin/#_authentication-flows)
## Authorization API (`client.authorization`)
Fine-grained authorization using Keycloak Authorization Services.
- Resource servers and resources
- Authorization scopes and permissions
- Policies (role, group, time, JS, etc.)
- Policy evaluation and testing
[Keycloak Documentation: Authorization Services](https://www.keycloak.org/docs/latest/authorization_services/)
## Client Scopes API (`client.client_scopes`)
Manage reusable scope configurations for clients.
- Create and configure client scopes
- Protocol mappers for scopes
- Default and optional client scopes
- Scope evaluation
[Keycloak Documentation: Client Scopes](https://www.keycloak.org/docs/latest/server_admin/#_client_scopes)
## Protocol Mappers API (`client.protocol_mappers`)
Configure how tokens and assertions are populated.
- Token claim mappings
- SAML attribute mappings
- User attribute and role mappings
- Hardcoded and dynamic values
[Keycloak Documentation: Protocol Mappers](https://www.keycloak.org/docs/latest/server_admin/#_protocol-mappers)
## Components API (`client.components`)
Manage pluggable components like user storage providers.
- User storage providers (LDAP, custom)
- Key providers and keystores
- Theme providers
- Other SPI implementations
[Keycloak Documentation: User Storage](https://www.keycloak.org/docs/latest/server_admin/#_user-storage-federation)
## Sessions API (`client.sessions`)
Monitor and manage active user and client sessions.
- List active sessions
- Session statistics
- Offline sessions
- Session revocation
[Keycloak Documentation: Sessions](https://www.keycloak.org/docs/latest/server_admin/#managing-user-sessions)
## Events API (`client.events`)
Access and configure audit and admin events.
- Query login and admin events
- Configure event listeners
- Event types and details
- Event retention policies
[Keycloak Documentation: Events](https://www.keycloak.org/docs/latest/server_admin/#configuring-auditing-to-track-events)
## Keys API (`client.keys`)
Manage realm cryptographic keys.
- Active signing and encryption keys
- Key rotation
- Algorithm configuration
- Certificate management
[Keycloak Documentation: Keys](https://www.keycloak.org/docs/latest/server_admin/#realm_keys)
## Organizations API (`client.organizations`)
Manage organizations (Keycloak 25+).
- Organization management
- Organization members
- Organization identity providers
- Multi-tenancy support
[Keycloak Documentation: Organizations](https://www.keycloak.org/docs/latest/server_admin/#_managing_organizations)
## Scope Mappings API (`client.scope_mappings`)
Manage client and realm scope mappings for users and groups.
- Realm-level role mappings
- Client-level role mappings
- Available and effective roles
- Composite role resolution
[Keycloak Documentation: Role Mappings](https://www.keycloak.org/docs/latest/server_admin/#_role_mappings)
## Client Role Mappings API (`client.client_role_mappings`)
Manage client-specific role assignments.
- Assign client roles to users
- Assign client roles to groups
- List available client roles
- Composite client role management
[Keycloak Documentation: Client Roles](https://www.keycloak.org/docs/latest/server_admin/#client-roles)
## Role Mapper API (`client.role_mapper`)
Manage realm-level role assignments.
- Assign realm roles to users
- Assign realm roles to groups
- List available realm roles
- Effective role calculation
[Keycloak Documentation: Realm Roles](https://www.keycloak.org/docs/latest/server_admin/#realm-roles)
## Roles by ID API (`client.roles_by_id`)
Manage roles using their unique IDs.
- Role CRUD operations by ID
- Composite role management by ID
- Role permissions by ID
- Cross-realm role operations
[Keycloak Documentation: Role Management](https://www.keycloak.org/docs/latest/server_admin/#_roles)
## Attack Detection API (`client.attack_detection`)
Manage brute force attack detection.
- View brute force status for users
- Clear brute force flags for users
- Reset attack detection counters
- Manage lockout policies
[Keycloak Documentation: Attack Detection](https://www.keycloak.org/docs/latest/server_admin/#password-policies)
## Client Initial Access API (`client.client_initial_access`)
Manage initial access tokens for dynamic client registration.
- Create initial access tokens
- List active tokens
- Delete tokens
- Configure token policies
[Keycloak Documentation: Client Registration](https://www.keycloak.org/docs/latest/securing_apps/#_client_registration)
## Client Attribute Certificate API (`client.client_attribute_certificate`)
Manage client certificates and keystores.
- Generate new certificates
- Upload certificate chains
- Download keystores (JKS/PKCS12)
- Certificate information retrieval
[Keycloak Documentation: Client Certificates](https://www.keycloak.org/docs/latest/server_admin/#_client-certificate-authentication)
## Client Registration Policy API (`client.client_registration_policy`)
Manage policies for dynamic client registration.
- List available policy providers
- Configure registration policies
- Set default client configurations
- Validation rules for client registration
[Keycloak Documentation: Client Registration Policies](https://www.keycloak.org/docs/latest/securing_apps/#_client_registration_policies)
# Implementation Status
* **Total API Endpoints**: 371 generated endpoints (excluding 23 deprecated template endpoints)
* **Categories with Wrappers**: 21
| API Module | Endpoints | Coverage | Status |
|----------------------------------|-----------|----------|--------------------------------------------------------------------------------------------|
| **Users** | 33 | 100% | Full CRUD, groups, sessions, credentials, consents, federated identity, profile management |
| **Realms** | 44 | 100% | Full CRUD, events, admin events, default groups, client scopes, partial import/export |
| **Clients** | 34 | 100% | Full CRUD, sessions, scopes, revocation, registration tokens |
| **Roles** | 27 | 100% | Full CRUD, composites, client roles, users/groups with role |
| **Groups** | 11 | 100% | Full CRUD, members, children, count |
| **Identity Providers** | 17 | 100% | Full CRUD, mappers, import/export, mapper types |
| **Authentication** | 39 | 100% | Flows, executions, required actions, configurations |
| **Authorization** | 31 | 100% | Resource server, resources, scopes, policies, permissions |
| **Client Scopes** | 5 | 100% | Full CRUD operations (excluding 5 deprecated template endpoints) |
| **Protocol Mappers** | 14 | 100% | Full mapper operations (excluding 7 deprecated template endpoints) |
| **Components** | 6 | 100% | Component management and sub-types |
| **Sessions** | 5 | 100% | Session management for realms, clients, users |
| **Events** | 6 | 100% | User events, admin events, configuration |
| **Keys** | 1 | 100% | Realm key management |
| **Organizations** | 19 | 100% | Full organization management (Keycloak 25+) |
| **Scope Mappings** | 22 | 100% | Realm and client scope mappings for users/groups (excluding 11 deprecated templates) |
| **Client Role Mappings** | 10 | 100% | User and group client role assignments and available roles |
| **Role Mapper** | 12 | 100% | User and group realm role assignments and effective roles |
| **Roles by ID** | 10 | 100% | Role operations by ID, composite management, cross-realm operations |
| **Attack Detection** | 3 | 100% | Brute force detection status and flag management |
| **Client Initial Access** | 3 | 100% | Initial access tokens for dynamic client registration |
| **Client Attribute Certificate** | 6 | 100% | Certificate generation, upload, keystore management |
| **Client Registration Policy** | 1 | 100% | Registration policy provider configuration |
Raw data
{
"_id": null,
"home_page": null,
"name": "ackc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "access management, api, authentication, authorization, client, enterprise authentication, identity, identity provider, jwt, keycloak, oauth2, openid connect, rbac, security, single sign-on, sso",
"author": null,
"author_email": "Phillip Sitbon <phillip.sitbon@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8d/e8/796bdcbaa27a486da3a4674883436b82664649fa554bd81c924ccfff4f41/ackc-1.0.0.tar.gz",
"platform": null,
"description": "# \ud83d\udd11 ACKC: API Client for Keycloak\n\n[](https://pypi.org/project/ackc/)\n[](https://pypi.org/project/ackc/)\n[](https://github.com/acie-io/ackc/releases)\n[](https://pypistats.org/packages/ackc)\n[](https://deepwiki.com/acie-io/ackc)\n\n[//]: # ([](https://deepwiki.com/acie-io/ackc))\n\nA comprehensive Python client library for Keycloak Admin REST API, providing a clean and typed interface for managing Keycloak resources.\n\nThe only dependencies are `niquests` for HTTP and `attrs` for data models, making it lightweight and easy to integrate.\n\n## Overview\n\nACKC is a fully-typed Python library that wraps Keycloak's Admin REST API.\n\nIt provides both synchronous and asynchronous interfaces for all major Keycloak administrative operations, with a focus on developer experience, type safety, and efficiency.\n\nThe author of this package was also a little fed up with the usual daily slog of CLI login and token acquisition before getting to work, so this library aims to make that process as painless as possible.\n\n## Features\n\n- **Complete API Coverage**: 100% implementation of all 371 non-deprecated Keycloak Admin API endpoints\n- **Type Safety**: Full type annotations with `attrs` models for all requests and responses \n- **Async Support**: Both sync and async methods for all operations (using the `niquests` library)\n- **Auto-generated Models**: Generated from Keycloak's OpenAPI specification using `openapi-python-client`\n- **CLI Tools**: Handy command-line utilities for common tasks like token acquisition and realm export\n- **Developer Friendly**: Clean API design with explicit parameters and comprehensive docstrings\n- **Multiple Auth Methods**: Support for client credentials, password grant, and device code flows\n\n## Installation\n\n`uv` is recommended, but you can also use other package managers like `pip`.\n\n```bash\nuv add ackc\n```\n\nStandalone tool installation is also available:\n\n```bash\nuv tool install --python 3.13 ackc\n```\n\n## Quick Start\n\n```python\nfrom ackc import KeycloakClient\n\nclient = KeycloakClient(\n server_url=\"https://keycloak.example.com\",\n client_id=\"admin-cli\",\n client_secret=\"your-secret\",\n realm=\"my-realm\", # Default realm for API calls\n auth_realm=\"master\", # Default realm for client authentication\n)\n\nwith client:\n users = client.users.get_all()\n realms = client.realms.get_all()\n\nasync def main():\n async with client:\n await client.users.aget_all()\n await client.realms.aget_all()\n```\n\n## Authentication Methods\n\nACKC supports multiple authentication flows:\n\n### Client Credentials (Default, Recommended for M2M)\n```python\nclient = KeycloakClient(\n server_url=\"https://keycloak.example.com\",\n client_id=\"admin-cli\", \n client_secret=\"secret\"\n)\nusers = client.users.get_all()\n```\n\n### Password Grant (Legacy Flow)\n```python\nclient = KeycloakClient(\n server_url=\"https://keycloak.example.com\",\n client_id=\"my-client\",\n client_secret=\"secret\"\n)\n\ntoken = client.get_token_password(\n username=\"admin\",\n password=\"admin\",\n scopes=[\"openid\", \"profile\", \"email\"]\n)\n```\n\n### Device Code Flow (For CLI Tools)\n```python\nclient = KeycloakClient(\n server_url=\"https://keycloak.example.com\",\n client_id=\"cli-client\"\n)\n\ndef device_callback(*, verification_uri, user_code, expires_in):\n print(f\"Please visit: {verification_uri}\")\n print(f\"User code: {user_code}\")\n print(f\"You have {expires_in} seconds to authorize\")\n\ntoken = client.get_token_device(\n scopes=[\"openid\", \"offline_access\"],\n callback=device_callback\n)\n```\n\n### Working with JWTs\n\nACKC provides methods for validating and working with JWTs:\n\n```python\nclaims = KeycloakClient.jwt_decode(jwt=\"your-jwt-token\")\nprint(f\"User: {claims.get('preferred_username')}\")\nprint(f\"Expires: {claims.get('exp')}\")\n\nneeds_refresh = KeycloakClient.jwt_needs_refresh(jwt=\"your-jwt-token\", buffer_seconds=300)\n\nclient = KeycloakClient(...)\nuser_info = client.jwt_userinfo(jwt=\"your-jwt-token\")\n\ntoken_info = client.jwt_introspect(jwt=\"your-jwt-token\")\n\nif token_info.get(\"active\"):\n print(f\"Token is valid for user: {token_info.get('username')}\")\n\nnew_token = client.jwt_refresh(refresh_token=\"your-refresh-token\")\n```\n\n## Async Support\n\nAll API methods have async equivalents with the `a` prefix, allowing for non-blocking operations:\n\n```python\nimport asyncio\nfrom ackc import KeycloakClient\n\nasync def main():\n client = KeycloakClient(\n server_url=\"https://keycloak.example.com\",\n client_id=\"admin-cli\",\n client_secret=\"secret\"\n )\n\n async with client:\n users = await client.users.aget_all()\n realms = await client.realms.aget_all()\n roles = await client.roles.aget_all()\n\nasyncio.run(main())\n```\n\n## CLI Tools\n\nACKC includes helpful CLI tools:\n\n### Get Token\n\nAcquire an access token for Keycloak using client, password, or device code flows.\nAlso supports 2FA for password grant using the `--otp`/`--otp-code` options.\n\n```bash\nauth-token --server https://keycloak.example.com --client admin-cli\n```\n\n### Export Realm\nExport a realm and associated data to JSON.\n\n```bash\nauth-realm-export my-realm\n```\n\n### Management Commands\n\nGet health status or dump Keycloak prometheus metrics.\nRequires `KC_HEALTH_ENABLED` or `KC_METRICS_ENABLED` to be set in Keycloak.\n\n```bash\nauth-mc --url http://localhost:9000 --json metrics \n```\n\n### Initialize Docker Environment\n\nCreates Keycloak Docker compose.yaml and .env files in the current directory for development.\n\n```bash\nackc-init \n```\n## Advanced Usage\n\n### Cloudflare Access Integration\n```python\n# Use with Cloudflare Access (+ Tunnel = HTTPS for local development or secure remote management)\n# Note: This gets you past Cloudflare, but you still need to authenticate with Keycloak.\n\nclient = KeycloakClient(\n server_url=\"https://keycloak.example.com\",\n cf_client_id='<your-cf-client-id>.access', # or CF_ACCESS_CLIENT_ID\n cf_client_secret='your-cf-secret', # or CF_ACCESS_CLIENT_SECRET\n)\n```\n\n### Per-Request Realm and Auth Realm Override\n```python\n# Initialize client for custom realm\nclient = KeycloakClient(server_url=\"...\", realm=\"my-realm\")\n\n# Override realm for specific calls\nusers = client.users.get_all(realm=\"other-realm\")\n\n# Use a different realm for API client authentication (master by default).\n# Recommended for backend production clients to maintain least privilege - the admin client should not have access to all realms.\ncompany_realm = \"my-company-realm\"\nclient = KeycloakClient(server_url=\"...\", auth_realm=company_realm, realm=company_realm)\n```\n\n### Direct API Access\n\n(Just don't do this)\n\n## Error Handling\n\n```python\nfrom ackc import KeycloakClient, AuthError\n\ntry:\n with KeycloakClient(...) as client:\n users = client.users.get_all()\n\nexcept AuthError as e:\n print(f\"Authentication failed: {e}\")\nexcept Exception as e:\n print(f\"API error: {e}\")\n```\n\n## Development\n\n### Regenerating API Client\n\nTo update the generated code when Keycloak API changes:\n\n```bash\npython gen/generate_client.py --download\n```\n\n## Requirements\n\n- Python 3.13+\n- Keycloak 26+ (tested with Keycloak 26.3)\n\n## License\n\nThis project is licensed under the Apache License 2.0. See the [license](license.md) file for details.\n\n## Contributing\n\nContributions are welcome! Please read the [contributing guidelines](contributing.md) for details on how to contribute to this project.\n\n## See Also\n\n- [Keycloak Documentation](https://www.keycloak.org/documentation)\n- [Keycloak Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/)\n\n## Appearances\n\n- [@thomasdarimont/awesome-keycloak](https://github.com/thomasdarimont/awesome-keycloak) (pending)\n\n\n# API Modules\n\nACKC organizes Keycloak's functionality into logical API modules:\n\n## Users API (`client.users`)\nManage users, credentials, roles, and user sessions.\n- Create, read, update, delete users\n- Manage user credentials and password resets\n- User role mappings and group memberships\n- User sessions and consent management\n\n[Keycloak Documentation: User Management](https://www.keycloak.org/docs/latest/server_admin/#assembly-managing-users_server_administration_guide)\n\n## Realms API (`client.realms`)\nConfigure realms, realm settings, and realm-level operations.\n- Create and configure realms\n- Manage realm settings and themes\n- Default groups and client scopes\n- Realm events and admin events\n- Localization and internationalization\n\n[Keycloak Documentation: Realms](https://www.keycloak.org/docs/latest/server_admin/#_configuring-realms)\n\n## Clients API (`client.clients`)\nManage OAuth2/OIDC clients and their configurations.\n- Create and configure clients\n- Client secrets and registration tokens\n- Client scopes and protocol mappers\n- Service accounts and permissions\n- Client session management\n\n[Keycloak Documentation: Clients](https://www.keycloak.org/docs/latest/server_admin/#_oidc_clients)\n\n## Roles API (`client.roles`)\nDefine and manage realm and client roles.\n- Create realm and client roles\n- Role hierarchies and composites\n- Role permissions and attributes\n- List role members\n\n[Keycloak Documentation: Roles](https://www.keycloak.org/docs/latest/server_admin/#proc-creating-realm-roles_server_administration_guide)\n\n## Groups API (`client.groups`)\nOrganize users into groups with hierarchical structures.\n- Create and manage groups\n- Group hierarchies and subgroups\n- Group role mappings\n- Group members management\n\n[Keycloak Documentation: Groups](https://www.keycloak.org/docs/latest/server_admin/#proc-managing-groups_server_administration_guide)\n\n## Identity Providers API (`client.identity_providers`)\nConfigure external identity providers for federation.\n- SAML and OIDC provider configuration\n- Social login providers (Google, GitHub, etc.)\n- Identity provider mappers\n- First broker login flows\n\n[Keycloak Documentation: Identity Providers](https://www.keycloak.org/docs/latest/server_admin/#_identity_broker)\n\n## Authentication API (`client.authentication`)\nCustomize authentication flows and requirements.\n- Authentication flows and executions\n- Required actions configuration\n- Authenticator providers\n- Password policies\n\n[Keycloak Documentation: Authentication](https://www.keycloak.org/docs/latest/server_admin/#_authentication-flows)\n\n## Authorization API (`client.authorization`)\nFine-grained authorization using Keycloak Authorization Services.\n- Resource servers and resources\n- Authorization scopes and permissions\n- Policies (role, group, time, JS, etc.)\n- Policy evaluation and testing\n\n[Keycloak Documentation: Authorization Services](https://www.keycloak.org/docs/latest/authorization_services/)\n\n## Client Scopes API (`client.client_scopes`)\nManage reusable scope configurations for clients.\n- Create and configure client scopes\n- Protocol mappers for scopes\n- Default and optional client scopes\n- Scope evaluation\n\n[Keycloak Documentation: Client Scopes](https://www.keycloak.org/docs/latest/server_admin/#_client_scopes)\n\n## Protocol Mappers API (`client.protocol_mappers`)\nConfigure how tokens and assertions are populated.\n- Token claim mappings\n- SAML attribute mappings\n- User attribute and role mappings\n- Hardcoded and dynamic values\n\n[Keycloak Documentation: Protocol Mappers](https://www.keycloak.org/docs/latest/server_admin/#_protocol-mappers)\n\n## Components API (`client.components`)\nManage pluggable components like user storage providers.\n- User storage providers (LDAP, custom)\n- Key providers and keystores\n- Theme providers\n- Other SPI implementations\n\n[Keycloak Documentation: User Storage](https://www.keycloak.org/docs/latest/server_admin/#_user-storage-federation)\n\n## Sessions API (`client.sessions`)\nMonitor and manage active user and client sessions.\n- List active sessions\n- Session statistics\n- Offline sessions\n- Session revocation\n\n[Keycloak Documentation: Sessions](https://www.keycloak.org/docs/latest/server_admin/#managing-user-sessions)\n\n## Events API (`client.events`)\nAccess and configure audit and admin events.\n- Query login and admin events\n- Configure event listeners\n- Event types and details\n- Event retention policies\n\n[Keycloak Documentation: Events](https://www.keycloak.org/docs/latest/server_admin/#configuring-auditing-to-track-events)\n\n## Keys API (`client.keys`)\nManage realm cryptographic keys.\n- Active signing and encryption keys\n- Key rotation\n- Algorithm configuration\n- Certificate management\n\n[Keycloak Documentation: Keys](https://www.keycloak.org/docs/latest/server_admin/#realm_keys)\n\n## Organizations API (`client.organizations`)\nManage organizations (Keycloak 25+).\n- Organization management\n- Organization members\n- Organization identity providers\n- Multi-tenancy support\n\n[Keycloak Documentation: Organizations](https://www.keycloak.org/docs/latest/server_admin/#_managing_organizations)\n\n## Scope Mappings API (`client.scope_mappings`)\nManage client and realm scope mappings for users and groups.\n- Realm-level role mappings\n- Client-level role mappings\n- Available and effective roles\n- Composite role resolution\n\n[Keycloak Documentation: Role Mappings](https://www.keycloak.org/docs/latest/server_admin/#_role_mappings)\n\n## Client Role Mappings API (`client.client_role_mappings`)\nManage client-specific role assignments.\n- Assign client roles to users\n- Assign client roles to groups\n- List available client roles\n- Composite client role management\n\n[Keycloak Documentation: Client Roles](https://www.keycloak.org/docs/latest/server_admin/#client-roles)\n\n## Role Mapper API (`client.role_mapper`)\nManage realm-level role assignments.\n- Assign realm roles to users\n- Assign realm roles to groups\n- List available realm roles\n- Effective role calculation\n\n[Keycloak Documentation: Realm Roles](https://www.keycloak.org/docs/latest/server_admin/#realm-roles)\n\n## Roles by ID API (`client.roles_by_id`)\nManage roles using their unique IDs.\n- Role CRUD operations by ID\n- Composite role management by ID\n- Role permissions by ID\n- Cross-realm role operations\n\n[Keycloak Documentation: Role Management](https://www.keycloak.org/docs/latest/server_admin/#_roles)\n\n## Attack Detection API (`client.attack_detection`)\nManage brute force attack detection.\n- View brute force status for users\n- Clear brute force flags for users\n- Reset attack detection counters\n- Manage lockout policies\n\n[Keycloak Documentation: Attack Detection](https://www.keycloak.org/docs/latest/server_admin/#password-policies)\n\n## Client Initial Access API (`client.client_initial_access`)\nManage initial access tokens for dynamic client registration.\n- Create initial access tokens\n- List active tokens\n- Delete tokens\n- Configure token policies\n\n[Keycloak Documentation: Client Registration](https://www.keycloak.org/docs/latest/securing_apps/#_client_registration)\n\n## Client Attribute Certificate API (`client.client_attribute_certificate`)\nManage client certificates and keystores.\n- Generate new certificates\n- Upload certificate chains\n- Download keystores (JKS/PKCS12)\n- Certificate information retrieval\n\n[Keycloak Documentation: Client Certificates](https://www.keycloak.org/docs/latest/server_admin/#_client-certificate-authentication)\n\n## Client Registration Policy API (`client.client_registration_policy`)\nManage policies for dynamic client registration.\n- List available policy providers\n- Configure registration policies\n- Set default client configurations\n- Validation rules for client registration\n\n[Keycloak Documentation: Client Registration Policies](https://www.keycloak.org/docs/latest/securing_apps/#_client_registration_policies)\n\n# Implementation Status\n\n* **Total API Endpoints**: 371 generated endpoints (excluding 23 deprecated template endpoints)\n* **Categories with Wrappers**: 21\n\n| API Module | Endpoints | Coverage | Status |\n|----------------------------------|-----------|----------|--------------------------------------------------------------------------------------------|\n| **Users** | 33 | 100% | Full CRUD, groups, sessions, credentials, consents, federated identity, profile management |\n| **Realms** | 44 | 100% | Full CRUD, events, admin events, default groups, client scopes, partial import/export |\n| **Clients** | 34 | 100% | Full CRUD, sessions, scopes, revocation, registration tokens |\n| **Roles** | 27 | 100% | Full CRUD, composites, client roles, users/groups with role |\n| **Groups** | 11 | 100% | Full CRUD, members, children, count |\n| **Identity Providers** | 17 | 100% | Full CRUD, mappers, import/export, mapper types |\n| **Authentication** | 39 | 100% | Flows, executions, required actions, configurations |\n| **Authorization** | 31 | 100% | Resource server, resources, scopes, policies, permissions |\n| **Client Scopes** | 5 | 100% | Full CRUD operations (excluding 5 deprecated template endpoints) |\n| **Protocol Mappers** | 14 | 100% | Full mapper operations (excluding 7 deprecated template endpoints) |\n| **Components** | 6 | 100% | Component management and sub-types |\n| **Sessions** | 5 | 100% | Session management for realms, clients, users |\n| **Events** | 6 | 100% | User events, admin events, configuration |\n| **Keys** | 1 | 100% | Realm key management |\n| **Organizations** | 19 | 100% | Full organization management (Keycloak 25+) |\n| **Scope Mappings** | 22 | 100% | Realm and client scope mappings for users/groups (excluding 11 deprecated templates) |\n| **Client Role Mappings** | 10 | 100% | User and group client role assignments and available roles |\n| **Role Mapper** | 12 | 100% | User and group realm role assignments and effective roles |\n| **Roles by ID** | 10 | 100% | Role operations by ID, composite management, cross-realm operations |\n| **Attack Detection** | 3 | 100% | Brute force detection status and flag management |\n| **Client Initial Access** | 3 | 100% | Initial access tokens for dynamic client registration |\n| **Client Attribute Certificate** | 6 | 100% | Certificate generation, upload, keystore management |\n| **Client Registration Policy** | 1 | 100% | Registration policy provider configuration |\n",
"bugtrack_url": null,
"license": null,
"summary": "API Client for Keycloak",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/acie-io/ackc#readme",
"Homepage": "https://github.com/acie-io/ackc",
"Issues": "https://github.com/acie-io/ackc/issues",
"Release Notes": "https://github.com/acie-io/ackc/releases",
"Repository": "https://github.com/acie-io/ackc.git"
},
"split_keywords": [
"access management",
" api",
" authentication",
" authorization",
" client",
" enterprise authentication",
" identity",
" identity provider",
" jwt",
" keycloak",
" oauth2",
" openid connect",
" rbac",
" security",
" single sign-on",
" sso"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1feafae8e941df7216b9502935c33ec721b2dada2e95bee46976868e3cf76e12",
"md5": "7a7e265c4c4d410c45e51f453e3fd9fb",
"sha256": "831526d758709c7df2a1def6766558104571cfd50ad8fe7a6573cea521025e6c"
},
"downloads": -1,
"filename": "ackc-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a7e265c4c4d410c45e51f453e3fd9fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 793827,
"upload_time": "2025-08-07T09:38:14",
"upload_time_iso_8601": "2025-08-07T09:38:14.977316Z",
"url": "https://files.pythonhosted.org/packages/1f/ea/fae8e941df7216b9502935c33ec721b2dada2e95bee46976868e3cf76e12/ackc-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8de8796bdcbaa27a486da3a4674883436b82664649fa554bd81c924ccfff4f41",
"md5": "6271050aa249f32eec1c8f8944f9a336",
"sha256": "f2354c9e76cfe1f76d143cff0d79771319a6127ae81f07deae08673a797d0261"
},
"downloads": -1,
"filename": "ackc-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "6271050aa249f32eec1c8f8944f9a336",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 273136,
"upload_time": "2025-08-07T09:38:16",
"upload_time_iso_8601": "2025-08-07T09:38:16.917802Z",
"url": "https://files.pythonhosted.org/packages/8d/e8/796bdcbaa27a486da3a4674883436b82664649fa554bd81c924ccfff4f41/ackc-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 09:38:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "acie-io",
"github_project": "ackc#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ackc"
}
JSON
