API Reference

REST API Reference

Complete reference for all Idenplane REST API endpoints. 376 endpoints across 55 API areas.

v1.0 Base URL: http://localhost:3000 Auth: X-Admin-API-Key header

Authentication

Admin API

Pass X-Admin-API-Key: <key> header or use the /admin/auth/login endpoint to get a JWT token.

Protocol Endpoints

OAuth/OIDC endpoints use client credentials (client_id + client_secret) or Bearer tokens as per OAuth 2.0 specs.

Admin API

Realms

Admin API Key 11 endpoints

Create, read, update, delete realms. Manage realm-level settings including SMTP, password policies, brute force protection, theming, and token lifespans.
/admin/realms
POST /admin/realms

Create a new realm

Details
Request Body
Field Type Required Description
name string Yes Realm slug (lowercase, e.g. "my-app")
displayName string No Human-readable display name
enabled boolean No Whether the realm is active (default: true)
accessTokenLifespan integer No Access token TTL in seconds (default: 300)
refreshTokenLifespan integer No Refresh token TTL in seconds (default: 1800)
smtpHost string No SMTP server hostname
smtpPort integer No SMTP server port (default: 587)
smtpUser string No SMTP username
smtpPassword string No SMTP password
smtpFrom string No Sender email address
smtpSecure boolean No Use TLS (default: false)
passwordMinLength integer No Minimum password length (default: 8)
passwordRequireUppercase boolean No Require uppercase letters
passwordRequireLowercase boolean No Require lowercase letters
passwordRequireDigits boolean No Require digits
passwordRequireSpecialChars boolean No Require special characters
passwordHistoryCount integer No Number of previous passwords to remember
passwordMaxAgeDays integer No Force password change after N days (0 = disabled)
bruteForceEnabled boolean No Enable brute force protection
maxLoginFailures integer No Max failed logins before lockout (default: 5)
lockoutDuration integer No Lockout duration in seconds (default: 900)
failureResetTime integer No Time to reset failure counter in seconds
permanentLockoutAfter integer No Permanent lockout after N temporary lockouts (0 = disabled)
registrationAllowed boolean No Allow self-service user registration (default: true)
requireEmailVerification boolean No Require email verification before login
mfaRequired boolean No Require MFA for all users
offlineTokenLifespan integer No Offline token TTL in seconds (default: 2592000)
eventsEnabled boolean No Enable login event recording
eventsExpiration integer No Event retention in seconds (default: 604800)
adminEventsEnabled boolean No Enable admin event recording
themeName string No Theme preset name (default: "idenplane")
theme object No Theme color overrides (logoUrl, primaryColor, etc.)
loginTheme string No Login page theme
accountTheme string No Account page theme
emailTheme string No Email template theme
Response

Returns the created realm object with redacted SMTP password.

GET /admin/realms

List all realms

Details
Response

Returns an array of all realm objects, ordered by creation date.

GET /admin/realms/themes

List available themes

Details
Response

Returns an array of theme names available on this server.

GET /admin/realms/:realmName

Get a realm by name

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns the realm object with redacted SMTP password.

PUT /admin/realms/:realmName

Update a realm

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
displayName string No Human-readable display name
enabled boolean No Whether the realm is active
accessTokenLifespan integer No Access token TTL in seconds
refreshTokenLifespan integer No Refresh token TTL in seconds
smtpHost string No SMTP server hostname
smtpPort integer No SMTP server port
smtpUser string No SMTP username
smtpPassword string No SMTP password (send actual value to update, or omit)
smtpFrom string No Sender email address
registrationAllowed boolean No Allow self-service registration
mfaRequired boolean No Require MFA for all users
themeName string No Theme preset name
theme object No Theme color overrides
Response

Returns the updated realm object.

DELETE /admin/realms/:realmName

Delete a realm

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns the deleted realm object.

PATCH /admin/realms/:realmName

Partially update a realm

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns the updated realm object.

POST /admin/realms/:realmName/smtp/test

Send test SMTP email

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
to string Yes Recipient email address
Response

Returns delivery confirmation or SMTP error details.

GET /admin/realms/:realmName/export

Export a realm to JSON

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Query Parameters
Name Type Required Description
includeUsers boolean No Include users in export (default: false)
includeSecrets boolean No Include client secrets and keys (default: false)
Response

Returns a full JSON representation of the realm.

POST /admin/realms/import

Import a realm from JSON

Details
Query Parameters
Name Type Required Description
overwrite boolean No Overwrite existing realm if found (default: false)
Request Body
Field Type Required Description
(body) object Yes Full realm JSON (as exported by the export endpoint)
Response

Returns the imported realm object.

POST /admin/realms/:realmName/email/test

Send a test email

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
to string Yes Recipient email address
Response

Returns { message: "Test email sent successfully" }.

Users

Admin API Key 12 endpoints

Manage users within a realm. Create, update, delete users, set passwords, manage email verification, and handle offline sessions.
/admin/realms/:realmName/users
POST /admin/realms/:realmName/users

Create a user in a realm

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
username string Yes Unique username (min 2 characters)
email string No Email address
firstName string No First name
lastName string No Last name
enabled boolean No Account enabled (default: true)
password string No Initial password (min 8 characters)
Response

Returns the created user object.

GET /admin/realms/:realmName/users

List users in a realm

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Query Parameters
Name Type Required Description
skip integer No Number of records to skip (default: 0)
limit integer No Max records to return (default: 50)
Response

Returns { total, users } with paginated user list.

GET /admin/realms/:realmName/users/:userId

Get a user by ID

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns the user object.

PUT /admin/realms/:realmName/users/:userId

Update a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Request Body
Field Type Required Description
username string No Username
email string No Email address
firstName string No First name
lastName string No Last name
enabled boolean No Account enabled
Response

Returns the updated user object.

DELETE /admin/realms/:realmName/users/:userId

Delete a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

204 No Content on success.

PATCH /admin/realms/:realmName/users/:userId

Partially update a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns the updated user object.

GET /admin/realms/:realmName/users/:userId/consents

List a user's consents

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns array of consent decisions granted by the user.

GET /admin/realms/:realmName/users/:userId/consents/history

Get a user's consent history

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns the full history of consent grants and revocations.

PUT /admin/realms/:realmName/users/:userId/reset-password

Set a user password

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Request Body
Field Type Required Description
password string Yes New password
Response

204 No Content on success.

POST /admin/realms/:realmName/users/:userId/send-verification-email

Send or resend verification email to a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns { message: "Verification email sent" }.

GET /admin/realms/:realmName/users/:userId/offline-sessions

List offline sessions for a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns array of offline session objects.

DELETE /admin/realms/:realmName/users/:userId/offline-sessions/:tokenId

Revoke an offline session

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
tokenId uuid Offline token ID
Response

204 No Content on success.

Clients

Admin API Key 8 endpoints

Register and manage OAuth 2.0 / OpenID Connect clients (applications). Configure redirect URIs, grant types, consent, and backchannel logout.
/admin/realms/:realmName/clients
POST /admin/realms/:realmName/clients

Create a client in a realm

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
clientId string Yes Client identifier slug (min 2 chars)
name string No Human-readable client name
description string No Client description
clientType enum No "CONFIDENTIAL" or "PUBLIC" (default: CONFIDENTIAL)
enabled boolean No Client enabled (default: true)
redirectUris string[] No Allowed redirect URIs
webOrigins string[] No Allowed CORS origins
grantTypes string[] No Allowed grant types (e.g. authorization_code, client_credentials)
requireConsent boolean No Require user consent on login (default: false)
backchannelLogoutUri string No Backchannel logout URL
backchannelLogoutSessionRequired boolean No Include session ID in logout token
Response

Returns the created client object with generated secret.

GET /admin/realms/:realmName/clients

List clients in a realm

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns array of client objects.

GET /admin/realms/:realmName/clients/:clientId

Get a client by ID

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Response

Returns the client object.

PUT /admin/realms/:realmName/clients/:clientId

Update a client

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Request Body
Field Type Required Description
name string No Client name
description string No Client description
enabled boolean No Client enabled
redirectUris string[] No Allowed redirect URIs
webOrigins string[] No Allowed CORS origins
grantTypes string[] No Allowed grant types
requireConsent boolean No Require user consent
backchannelLogoutUri string No Backchannel logout URL
Response

Returns the updated client object.

DELETE /admin/realms/:realmName/clients/:clientId

Delete a client

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Response

204 No Content on success.

PATCH /admin/realms/:realmName/clients/:clientId

Partially update a client

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Response

Returns the updated client object.

POST /admin/realms/:realmName/clients/:clientId/regenerate-secret

Regenerate client secret

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Response

Returns the client with a new secret.

GET /admin/realms/:realmName/clients/:clientId/service-account-user

Get service account user for a client

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Response

Returns the service account user object.

Realm Roles

Admin API Key 6 endpoints

Create and manage realm-level roles. Realm roles apply across all clients in a realm.
/admin/realms/:realmName/roles
POST /admin/realms/:realmName/roles

Create a realm role

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
name string Yes Role name
description string No Role description
Response

Returns the created role object.

GET /admin/realms/:realmName/roles

List realm roles

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns array of realm role objects.

GET /admin/realms/:realmName/roles/:roleName

Get a realm role by name

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
roleName string Role name
Response

Returns the realm role object.

PUT /admin/realms/:realmName/roles/:roleName

Update a realm role

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
roleName string Role name
Response

Returns the updated realm role.

PATCH /admin/realms/:realmName/roles/:roleName

Partially update a realm role

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
roleName string Role name
Response

Returns the updated realm role.

DELETE /admin/realms/:realmName/roles/:roleName

Delete a realm role

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
roleName string Role name
Response

204 No Content on success.

Client Roles

Admin API Key 2 endpoints

Create and list roles scoped to a specific client application.
/admin/realms/:realmName/clients/:clientId/roles
POST /admin/realms/:realmName/clients/:clientId/roles

Create a client role

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Request Body
Field Type Required Description
name string Yes Role name
description string No Role description
Response

Returns the created client role object.

GET /admin/realms/:realmName/clients/:clientId/roles

List client roles

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Response

Returns array of client role objects.

User Role Mappings

Admin API Key 6 endpoints

Assign and remove realm roles and client roles from users.
/admin/realms/:realmName/users/:userId/role-mappings
POST /admin/realms/:realmName/users/:userId/role-mappings/realm

Assign realm roles to a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Request Body
Field Type Required Description
roleNames string[] Yes Array of realm role names to assign
Response

Returns confirmation of assigned roles.

GET /admin/realms/:realmName/users/:userId/role-mappings/realm

List a user's realm roles

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns array of assigned realm role objects.

DELETE /admin/realms/:realmName/users/:userId/role-mappings/realm

Remove realm roles from a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Request Body
Field Type Required Description
roleNames string[] Yes Array of realm role names to remove
Response

Returns confirmation of removed roles.

POST /admin/realms/:realmName/users/:userId/role-mappings/clients/:clientId

Assign client roles to a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
clientId string Client ID (slug)
Request Body
Field Type Required Description
roleNames string[] Yes Array of client role names to assign
Response

Returns confirmation of assigned roles.

GET /admin/realms/:realmName/users/:userId/role-mappings/clients/:clientId

List a user's client roles

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
clientId string Client ID (slug)
Response

Returns array of assigned client role objects.

DELETE /admin/realms/:realmName/users/:userId/role-mappings/clients/:clientId

Remove client roles from a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
clientId string Client ID (slug)
Request Body
Field Type Required Description
roleNames string[] Yes Array of client role names to remove
Response

Returns confirmation of removed roles.

Groups

Admin API Key 13 endpoints

Manage user groups with hierarchical structure. Assign users to groups and map roles to groups for bulk role assignment.
/admin/realms/:realmName/groups
POST /admin/realms/:realmName/groups

Create a group

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
name string Yes Group name
description string No Group description
parentId uuid No Parent group ID (for subgroups)
Response

Returns the created group object.

GET /admin/realms/:realmName/groups

List all groups (tree structure)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns array of top-level groups with nested children.

GET /admin/realms/:realmName/groups/:groupId

Get group by ID

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
groupId uuid Group ID
Response

Returns group object with children and member/role counts.

PUT /admin/realms/:realmName/groups/:groupId

Update a group

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
groupId uuid Group ID
Request Body
Field Type Required Description
name string No Group name
description string No Group description
Response

Returns the updated group object.

DELETE /admin/realms/:realmName/groups/:groupId

Delete a group

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
groupId uuid Group ID
Response

Returns the deleted group.

GET /admin/realms/:realmName/groups/:groupId/members

List group members

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
groupId uuid Group ID
Response

Returns array of user objects in the group.

PUT /admin/realms/:realmName/users/:userId/groups/:groupId

Add user to group

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
groupId uuid Group ID
Response

Returns the user-group association.

POST /admin/realms/:realmName/users/:userId/groups/:groupId

Add user to group (Keycloak-compat)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
groupId uuid Group ID
Response

Returns the user-group association. Keycloak-compatible alias for PUT.

DELETE /admin/realms/:realmName/users/:userId/groups/:groupId

Remove user from group

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
groupId uuid Group ID
Response

Returns the deleted association.

GET /admin/realms/:realmName/users/:userId/groups

List user's groups

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns array of groups the user belongs to.

GET /admin/realms/:realmName/groups/:groupId/role-mappings

Get group role mappings

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
groupId uuid Group ID
Response

Returns array of roles assigned to the group.

POST /admin/realms/:realmName/groups/:groupId/role-mappings

Assign roles to group

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
groupId uuid Group ID
Request Body
Field Type Required Description
roleNames string[] Yes Array of role names to assign
Response

Returns confirmation of assigned roles.

DELETE /admin/realms/:realmName/groups/:groupId/role-mappings

Remove roles from group

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
groupId uuid Group ID
Request Body
Field Type Required Description
roleNames string[] Yes Array of role names to remove
Response

Returns confirmation of removed roles.

Sessions

Admin API Key 4 endpoints

View and manage active user sessions (OAuth tokens and SSO sessions). Revoke individual sessions or all sessions for a user.
/admin/realms/:realmName/sessions
GET /admin/realms/:realmName/sessions

List all active sessions in the realm

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns array of active session objects.

GET /admin/realms/:realmName/users/:userId/sessions

List active sessions for a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns array of session objects for the user.

DELETE /admin/realms/:realmName/sessions/:sessionId

Revoke a specific session

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
sessionId uuid Session ID
Query Parameters
Name Type Required Description
type enum No "oauth" or "sso" (default: "oauth")
Response

Returns confirmation of revoked session.

DELETE /admin/realms/:realmName/users/:userId/sessions

Revoke all sessions for a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns count of revoked sessions.

Events

Admin API Key 5 endpoints

Query and manage login events and admin events. Filter by type, user, client, and date range.
/admin/realms/:realmName/events
GET /admin/realms/:realmName/events

Query login events

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Query Parameters
Name Type Required Description
type string No Event type filter (e.g. LOGIN, LOGIN_ERROR, REGISTER)
userId uuid No Filter by user ID
clientId string No Filter by client ID
dateFrom ISO 8601 No Start date filter
dateTo ISO 8601 No End date filter
first integer No Offset for pagination
max integer No Max results to return
Response

Returns array of login event objects.

DELETE /admin/realms/:realmName/events

Clear login events

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

204 No Content on success.

GET /admin/realms/:realmName/admin-events

Query admin events

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Query Parameters
Name Type Required Description
operationType string No Operation type filter (e.g. CREATE, UPDATE, DELETE)
resourceType string No Resource type filter (e.g. USER, CLIENT, REALM)
dateFrom ISO 8601 No Start date filter
dateTo ISO 8601 No End date filter
first integer No Offset for pagination
max integer No Max results to return
Response

Returns array of admin event objects.

GET /admin/realms/:realmName/events/login/export

Export login events (CSV)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns text/csv export of login events with the same filters as the query endpoint.

GET /admin/realms/:realmName/events/admin/export

Export admin events (CSV)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns text/csv export of admin events with the same filters as the query endpoint.

Client Scopes

Admin API Key 15 endpoints

Manage OAuth scopes and protocol mappers. Assign default and optional scopes to clients. Configure token claims via protocol mappers.
/admin/realms/:realmName/client-scopes
GET /admin/realms/:realmName/client-scopes

List client scopes in a realm

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns array of client scope objects with protocol mappers.

GET /admin/realms/:realmName/client-scopes/:scopeId

Get a client scope

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
scopeId uuid Client scope ID
Response

Returns the client scope object with protocol mappers.

POST /admin/realms/:realmName/client-scopes

Create a client scope

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
name string Yes Scope name (e.g. "profile", "custom-scope")
description string No Scope description
protocol string No Protocol (default: "openid-connect")
Response

Returns the created client scope.

PUT /admin/realms/:realmName/client-scopes/:scopeId

Update a client scope

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
scopeId uuid Client scope ID
Request Body
Field Type Required Description
name string No Scope name
description string No Scope description
Response

Returns the updated client scope.

DELETE /admin/realms/:realmName/client-scopes/:scopeId

Delete a client scope

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
scopeId uuid Client scope ID
Response

204 No Content on success.

GET /admin/realms/:realmName/client-scopes/:scopeId/protocol-mappers

List protocol mappers for a client scope

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
scopeId uuid Client scope ID
Response

Returns array of protocol mappers attached to the scope.

POST /admin/realms/:realmName/client-scopes/:scopeId/protocol-mappers

Add a protocol mapper to a scope

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
scopeId uuid Client scope ID
Request Body
Field Type Required Description
name string Yes Mapper name
mapperType string Yes Mapper type (e.g. "oidc-usermodel-attribute-mapper")
protocol string No Protocol (default: "openid-connect")
config object No Mapper configuration (claim name, attribute name, etc.)
Response

Returns the created protocol mapper.

PUT /admin/realms/:realmName/client-scopes/:scopeId/protocol-mappers/:mapperId

Update a protocol mapper

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
scopeId uuid Client scope ID
mapperId uuid Mapper ID
Request Body
Field Type Required Description
name string No Mapper name
config object No Mapper configuration
Response

Returns the updated protocol mapper.

DELETE /admin/realms/:realmName/client-scopes/:scopeId/protocol-mappers/:mapperId

Delete a protocol mapper

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
scopeId uuid Client scope ID
mapperId uuid Mapper ID
Response

204 No Content on success.

GET /admin/realms/:realmName/clients/:clientId/default-client-scopes

Get default scopes assigned to a client

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Response

Returns array of default scope objects.

POST /admin/realms/:realmName/clients/:clientId/default-client-scopes

Assign a default scope to a client

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Request Body
Field Type Required Description
clientScopeId uuid Yes Client scope ID to assign
Response

Returns the scope assignment.

DELETE /admin/realms/:realmName/clients/:clientId/default-client-scopes/:scopeId

Remove a default scope from a client

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
scopeId uuid Client scope ID
Response

204 No Content on success.

GET /admin/realms/:realmName/clients/:clientId/optional-client-scopes

Get optional scopes assigned to a client

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Response

Returns array of optional scope objects.

POST /admin/realms/:realmName/clients/:clientId/optional-client-scopes

Assign an optional scope to a client

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
Request Body
Field Type Required Description
clientScopeId uuid Yes Client scope ID to assign
Response

Returns the scope assignment.

DELETE /admin/realms/:realmName/clients/:clientId/optional-client-scopes/:scopeId

Remove an optional scope from a client

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
clientId string Client ID (slug)
scopeId uuid Client scope ID
Response

204 No Content on success.

Identity Providers

Admin API Key 5 endpoints

Configure external identity providers (social login) for a realm. Supports OIDC-based providers like Google, GitHub, and custom providers.
/admin/realms/:realmName/identity-providers
POST /admin/realms/:realmName/identity-providers

Create an identity provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
alias string Yes Unique alias (e.g. "google", "github")
displayName string No Display name shown to users
providerType string Yes Provider type (e.g. "oidc", "google", "github")
enabled boolean No Provider enabled (default: true)
clientId string Yes OAuth client ID from external provider
clientSecret string Yes OAuth client secret from external provider
authorizationUrl string Yes Authorization endpoint URL
tokenUrl string Yes Token endpoint URL
userinfoUrl string No Userinfo endpoint URL
jwksUrl string No JWKS endpoint URL
issuer string No Expected issuer value
defaultScopes string No Default scopes (space-separated)
trustEmail boolean No Trust email from provider
syncUserProfile boolean No Sync profile on each login
Response

Returns the created identity provider object.

GET /admin/realms/:realmName/identity-providers

List identity providers

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns array of identity provider objects.

GET /admin/realms/:realmName/identity-providers/:alias

Get identity provider by alias

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
alias string Provider alias
Response

Returns the identity provider object.

PUT /admin/realms/:realmName/identity-providers/:alias

Update identity provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
alias string Provider alias
Response

Returns the updated identity provider.

DELETE /admin/realms/:realmName/identity-providers/:alias

Delete identity provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
alias string Provider alias
Response

Returns the deleted identity provider.

User Federation

Admin API Key 7 endpoints

Configure LDAP user federation providers. Sync users from external LDAP/Active Directory servers.
/admin/realms/:realmName/user-federation
POST /admin/realms/:realmName/user-federation

Create a user federation provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
name string Yes Provider name
providerType string Yes Provider type (e.g. "ldap")
enabled boolean No Provider enabled
priority integer No Evaluation priority
connectionUrl string Yes LDAP server URL (e.g. "ldap://ldap.example.com:389")
bindDn string Yes Bind DN for LDAP authentication
bindCredential string Yes Bind password
usersDn string Yes Base DN for user search
userObjectClass string No LDAP user object class (default: "inetOrgPerson")
usernameLdapAttr string No LDAP attribute for username (default: "uid")
syncMode string No Sync mode: "IMPORT" or "READ_ONLY"
syncPeriod integer No Auto-sync interval in seconds
importEnabled boolean No Enable user import on sync
Response

Returns the created federation provider.

GET /admin/realms/:realmName/user-federation

List user federation providers

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns array of federation provider objects.

GET /admin/realms/:realmName/user-federation/:id

Get a user federation provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Federation provider ID
Response

Returns the federation provider object.

PUT /admin/realms/:realmName/user-federation/:id

Update a user federation provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Federation provider ID
Response

Returns the updated federation provider.

DELETE /admin/realms/:realmName/user-federation/:id

Delete a user federation provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Federation provider ID
Response

Returns the deleted federation provider.

POST /admin/realms/:realmName/user-federation/:id/test-connection

Test LDAP connection

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Federation provider ID
Response

Returns { success: true } or error details.

POST /admin/realms/:realmName/user-federation/:id/sync

Trigger full LDAP sync

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Federation provider ID
Response

Returns sync results (created, updated, failed counts).

SAML Service Providers

Admin API Key 5 endpoints

Register and manage SAML 2.0 service providers. Idenplane acts as the SAML Identity Provider (IdP).
/admin/realms/:realmName/saml-service-providers
POST /admin/realms/:realmName/saml-service-providers

Register a SAML service provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
entityId string Yes SP Entity ID (unique identifier)
name string Yes SP display name
enabled boolean No SP enabled (default: true)
acsUrl string Yes Assertion Consumer Service URL
sloUrl string No Single Logout URL
certificate string No SP signing certificate (PEM)
nameIdFormat string No NameID format (default: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress")
signAssertions boolean No Sign SAML assertions (default: true)
signResponses boolean No Sign SAML responses (default: true)
attributeStatements object No Custom attribute statement mappings
Response

Returns the created SAML SP object.

GET /admin/realms/:realmName/saml-service-providers

List SAML service providers

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns array of SAML SP objects.

GET /admin/realms/:realmName/saml-service-providers/:id

Get a SAML service provider by ID

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid SAML SP ID
Response

Returns the SAML SP object.

PUT /admin/realms/:realmName/saml-service-providers/:id

Update a SAML service provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid SAML SP ID
Response

Returns the updated SAML SP object.

DELETE /admin/realms/:realmName/saml-service-providers/:id

Delete a SAML service provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid SAML SP ID
Response

204 No Content on success.

MFA Administration

Admin API Key 3 endpoints

Check MFA status and reset MFA for users. Admins can disable TOTP for a user if they lose their device.
/admin/realms/:realmName/users/:userId/mfa
GET /admin/realms/:realmName/users/:userId/mfa/status

Check if user has MFA enabled

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Returns { enabled: boolean }.

DELETE /admin/realms/:realmName/users/:userId/mfa

Reset/disable MFA for a user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

204 No Content on success.

DELETE /admin/realms/:realmName/users/:userId/mfa/totp

Delete a user's TOTP device

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

204 No Content. Removes the TOTP credential without affecting other MFA factors.

Brute Force Protection

Admin API Key 3 endpoints

View locked users and unlock accounts locked by brute force protection.
/admin/realms/:realmName/brute-force
GET /admin/realms/:realmName/brute-force/locked-users

List locked users in a realm

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns array of locked user records with failure counts and lockout times.

POST /admin/realms/:realmName/brute-force/users/:userId/unlock

Unlock a locked user

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

204 No Content on success.

POST /admin/realms/:realmName/brute-force/users/:userId

Unlock user (Keycloak-compat alias)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
userId uuid User ID
Response

Keycloak-compatible alias for the /unlock endpoint.

Admin Authentication

Public / Admin Token 3 endpoints

Authenticate as an admin user to access the admin console and admin API.
/admin/auth
POST /admin/auth/login

Admin login

Details
Request Body
Field Type Required Description
username string Yes Admin username
password string Yes Admin password
Response

Returns { accessToken, user } with JWT admin token.

GET /admin/auth/me

Get current admin user info

Details
Response

Returns the authenticated admin user object.

POST /admin/auth/logout

Admin logout

Details
Response

Invalidates the admin session token. Returns 204 No Content.

Organizations (B2B)

Admin API Key 19 endpoints

B2B multi-tenancy: organizations, members, invitations, domain verification, and per-org SSO connections.
/admin/realms/:realmName/organizations
POST /admin/realms/:realmName/organizations

Create an organization in a realm

GET /admin/realms/:realmName/organizations

List all organizations in a realm

GET /admin/realms/:realmName/organizations/:slug

Get an organization by slug

PUT /admin/realms/:realmName/organizations/:slug

Update an organization

DELETE /admin/realms/:realmName/organizations/:slug

Delete an organization

GET /admin/realms/:realmName/organizations/:slug/members

List members of an organization

POST /admin/realms/:realmName/organizations/:slug/members

Add a user to an organization

PUT /admin/realms/:realmName/organizations/:slug/members/:userId

Update a member's role

DELETE /admin/realms/:realmName/organizations/:slug/members/:userId

Remove a user from an organization

GET /admin/realms/:realmName/organizations/:slug/invitations

List invitations for an organization

POST /admin/realms/:realmName/organizations/:slug/invitations

Create an invitation to an organization

POST /admin/realms/:realmName/organizations/:slug/invitations/:token/accept

Accept an invitation

POST /admin/realms/:realmName/organizations/:slug/verify-domain/initiate

Initiate domain verification (issue DNS TXT challenge)

POST /admin/realms/:realmName/organizations/:slug/verify-domain

Verify domain ownership via DNS TXT lookup

GET /admin/realms/:realmName/organizations/:slug/sso-connections

List SSO connections for an organization

POST /admin/realms/:realmName/organizations/:slug/sso-connections

Create an SSO connection for an organization

GET /admin/realms/:realmName/organizations/:slug/sso-connections/:connectionId

Get a specific SSO connection

PUT /admin/realms/:realmName/organizations/:slug/sso-connections/:connectionId

Update an SSO connection

DELETE /admin/realms/:realmName/organizations/:slug/sso-connections/:connectionId

Delete an SSO connection

Custom Attributes

Admin API Key 8 endpoints

Realm-level custom attribute definitions and per-user attribute values.
/admin/realms/:realmName/custom-attributes
POST /admin/realms/:realmName/custom-attributes

Create a custom attribute definition for a realm

GET /admin/realms/:realmName/custom-attributes

List custom attribute definitions for a realm

PUT /admin/realms/:realmName/custom-attributes

Bulk update custom attribute definitions

GET /admin/realms/:realmName/custom-attributes/:attributeId

Get a custom attribute definition by ID

PUT /admin/realms/:realmName/custom-attributes/:attributeId

Update a custom attribute definition

DELETE /admin/realms/:realmName/custom-attributes/:attributeId

Delete a custom attribute definition

GET /admin/realms/:realmName/users/:userId/attributes

Get attribute values for a user

PUT /admin/realms/:realmName/users/:userId/attributes

Set attribute values for a user

Non-Human Identity (NHI)

Admin API Key 25 endpoints

Service workloads, bots, and machines: identities, credentials, rotation policies, device certificates, fleet bulk-register, and audit log.
/admin/realms/:realmName/nhi
POST /admin/realms/:realmName/nhi

Create an NHI identity in a realm

GET /admin/realms/:realmName/nhi

List NHI identities in a realm

POST /admin/realms/:realmName/nhi/devices/bulk-register

Bulk register devices for fleet management

POST /admin/realms/:realmName/nhi/device-certificates

Generate a device certificate (self-signed)

POST /admin/realms/:realmName/nhi/credential-policies

Create a credential rotation policy

GET /admin/realms/:realmName/nhi/credential-policies

List credential rotation policies in a realm

GET /admin/realms/:realmName/nhi/credential-policies/:policyId

Get a credential rotation policy by ID

PUT /admin/realms/:realmName/nhi/credential-policies/:policyId

Update a credential rotation policy

DELETE /admin/realms/:realmName/nhi/credential-policies/:policyId

Delete a credential rotation policy

GET /admin/realms/:realmName/nhi/credential-policies/:policyId/rotation-status

Get rotation status for a specific policy

GET /admin/realms/:realmName/nhi/rotation-status

Get aggregate rotation status summary

GET /admin/realms/:realmName/nhi/audit-logs

Query NHI audit logs

DELETE /admin/realms/:realmName/nhi/audit-logs

Clear NHI audit logs

GET /admin/realms/:realmName/nhi/:id

Get an NHI identity by ID

PUT /admin/realms/:realmName/nhi/:id

Update an NHI identity

DELETE /admin/realms/:realmName/nhi/:id

Delete an NHI identity

POST /admin/realms/:realmName/nhi/:id/suspend

Suspend an NHI identity

POST /admin/realms/:realmName/nhi/:id/reactivate

Reactivate a suspended NHI identity

POST /admin/realms/:realmName/nhi/:id/decommission

Decommission an NHI identity (irreversible)

POST /admin/realms/:realmName/nhi/:id/credentials

Create a credential for an NHI identity

GET /admin/realms/:realmName/nhi/:id/credentials

List credentials for an NHI identity

POST /admin/realms/:realmName/nhi/:id/credentials/:credentialId/revoke

Revoke a credential

POST /admin/realms/:realmName/nhi/:id/credentials/:credentialId/rotate

Rotate a credential (issue replacement, revoke old)

POST /admin/realms/:realmName/nhi/:id/certificate

Set certificate for an NHI identity

GET /admin/realms/:realmName/nhi/:id/stats

Get usage statistics for an NHI identity

Service Accounts

Admin API Key 10 endpoints

Machine identities with API keys, metrics, rotation, and revocation.
/admin/realms/:realmName/service-accounts
POST /admin/realms/:realmName/service-accounts

Create a service account in a realm

GET /admin/realms/:realmName/service-accounts

List service accounts in a realm

GET /admin/realms/:realmName/service-accounts/:id

Get a service account by ID

PUT /admin/realms/:realmName/service-accounts/:id

Update a service account

DELETE /admin/realms/:realmName/service-accounts/:id

Delete a service account

POST /admin/realms/:realmName/service-accounts/:id/api-keys

Create an API key for a service account

GET /admin/realms/:realmName/service-accounts/:id/api-keys

List API keys for a service account

POST /admin/realms/:realmName/service-accounts/:id/api-keys/:keyId/revoke

Revoke an API key

POST /admin/realms/:realmName/service-accounts/:id/api-keys/:keyId/rotate

Rotate an API key (issue replacement, revoke old)

GET /admin/realms/:realmName/service-accounts/:id/metrics

Get usage metrics for a service account

SCIM Provisioning (Admin)

Admin API Key 11 endpoints

Per-realm SCIM provisioning tokens, attribute mappings, and provisioning status.
/admin/realms/:realmName/scim
POST /admin/realms/:realmName/scim/tokens

Create a new SCIM provisioning token

GET /admin/realms/:realmName/scim/tokens

Get all SCIM tokens for the realm

GET /admin/realms/:realmName/scim/tokens/:tokenId

Get a specific SCIM token

DELETE /admin/realms/:realmName/scim/tokens/:tokenId

Delete a SCIM token

PUT /admin/realms/:realmName/scim/tokens/:tokenId/revoke

Revoke a SCIM token

PUT /admin/realms/:realmName/scim/tokens/:tokenId/enable

Enable a SCIM token

PUT /admin/realms/:realmName/scim/tokens/:tokenId/disable

Disable a SCIM token

GET /admin/realms/:realmName/scim/attribute-mappings

Get SCIM attribute mappings for the realm

POST /admin/realms/:realmName/scim/attribute-mappings

Create a SCIM attribute mapping

DELETE /admin/realms/:realmName/scim/attribute-mappings/:mappingId

Delete a SCIM attribute mapping

GET /admin/realms/:realmName/scim/status

Get SCIM provisioning status for the realm

Webhooks

Admin API Key 8 endpoints

Webhook subscriptions, partial updates, delivery logs, and synthetic test events.
/admin/realms/:realmName/webhooks
POST /admin/realms/:realmName/webhooks

Create a webhook in a realm

GET /admin/realms/:realmName/webhooks

List webhooks in a realm

GET /admin/realms/:realmName/webhooks/:id

Get a webhook by ID

PUT /admin/realms/:realmName/webhooks/:id

Update a webhook

PATCH /admin/realms/:realmName/webhooks/:id

Partially update a webhook

DELETE /admin/realms/:realmName/webhooks/:id

Delete a webhook

POST /admin/realms/:realmName/webhooks/:id/test

Send a test event to the webhook

GET /admin/realms/:realmName/webhooks/:id/deliveries

List delivery logs for a webhook

Stats

Admin API Key 2 endpoints

Dashboard counters and consent statistics per realm.
/admin/realms/:realmName
GET /admin/realms/:realmName/stats

Get dashboard statistics for a realm

GET /admin/realms/:realmName/stats/consents

Get consent statistics for a realm

Self-Service Registration

Public (user) / Admin API Key (admin/*) 11 endpoints

Public registration flow plus admin moderation of pending registrations and registration field configuration.
/realms/:realmName/registration
POST /realms/:realmName/registration/register

Register a new user

POST /realms/:realmName/registration/verify-email

Verify email address with token

POST /realms/:realmName/registration/resend-verification

Resend email verification

GET /realms/:realmName/registration/fields

Get enabled registration fields for a realm

GET /realms/:realmName/registration/pending

Get pending registrations

POST /realms/:realmName/registration/approve/:userId

Approve a pending registration

POST /realms/:realmName/registration/reject/:userId

Reject a pending registration

GET /realms/:realmName/registration/admin/fields

Get all registration fields (admin)

POST /realms/:realmName/registration/admin/fields

Create a new registration field

PUT /realms/:realmName/registration/admin/fields/:fieldId

Update a registration field

DELETE /realms/:realmName/registration/admin/fields/:fieldId

Delete a registration field

Impersonation

Admin API Key 2 endpoints

Admin impersonation: start an impersonation session for a user and explicitly end the current one.
/admin/realms/:realmName
POST /admin/realms/:realmName/users/:userId/impersonate

Start an admin-impersonation session for a user

POST /admin/realms/:realmName/impersonation/end

End the current admin-impersonation session

Themes

Admin API Key 11 endpoints

Theme CRUD plus publishing, versioning, restore, server-side preview rendering, and asset uploads.
/admin/realms/:realmName/themes
POST /admin/realms/:realmName/themes

Create a new theme

GET /admin/realms/:realmName/themes

List all themes for a realm

GET /admin/realms/:realmName/themes/built-in

List available built-in themes

GET /admin/realms/:realmName/themes/:themeId

Get a theme by ID

PUT /admin/realms/:realmName/themes/:themeId

Update a theme

DELETE /admin/realms/:realmName/themes/:themeId

Delete a theme

POST /admin/realms/:realmName/themes/:themeId/publish

Publish a theme

GET /admin/realms/:realmName/themes/:themeId/versions

Get version history for a theme

POST /admin/realms/:realmName/themes/:themeId/restore/:version

Restore a theme to a specific version

POST /admin/realms/:realmName/themes/preview

Render a server-side theme preview

POST /admin/realms/:realmName/themes/assets/upload

Upload theme assets (logos, favicons, etc.)

Plugins

Admin API Key 5 endpoints

List, enable, disable, and uninstall server-side plugins and extensions.
/admin/plugins
GET /admin/plugins

List all installed plugins

GET /admin/plugins/:name

Get details for a specific plugin

POST /admin/plugins/:name/enable

Enable a plugin

POST /admin/plugins/:name/disable

Disable a plugin

DELETE /admin/plugins/:name

Uninstall a plugin

Migration (Keycloak / Auth0)

Admin API Key 2 endpoints

One-shot imports from Keycloak realm export JSON or an Auth0 Management API export.
/admin/migration
POST /admin/migration/keycloak

Import from Keycloak realm export JSON

POST /admin/migration/auth0

Import from Auth0 Management API export

System Version

Admin API Key 1 endpoints

Server version metadata for upgrade tooling and dashboards.
/admin/system
GET /admin/system/version

Get server version metadata

Upgrade & Rollback

Admin API Key 10 endpoints

Server upgrade lifecycle: pre-validation, execution, status, history, rollback capability checks, and post-upgrade health.
/admin/upgrade
POST /admin/upgrade

Start an upgrade to a target version

GET /admin/upgrade/status

Get the most recent upgrade status

GET /admin/upgrade/history

Get upgrade history

GET /admin/upgrade/audit

Get upgrade audit entries for CLI

GET /admin/upgrade/:upgradeId

Get upgrade state by ID

GET /admin/upgrade/rollback/capability

Check if rollback is possible

POST /admin/upgrade/rollback

Execute rollback to previous version

GET /admin/upgrade/pre-validation

Run pre-upgrade validation checks

GET /admin/upgrade/health

Run post-upgrade health checks

GET /admin/upgrade/config-compatibility

Check configuration compatibility for a version

Setup Wizard

Bootstrap token (first run) 11 endpoints

First-run admin onboarding: admin account, realm settings, SMTP config, first client, and wizard lifecycle.
/setup-wizard
GET /setup-wizard/status

Get wizard status and step information

GET /setup-wizard/state

Get current wizard state

POST /setup-wizard/admin-account

Save admin account (Step 1)

POST /setup-wizard/realm-settings

Save realm settings (Step 2)

POST /setup-wizard/smtp-config

Save SMTP configuration (Step 3)

POST /setup-wizard/smtp/test

Test SMTP connection

POST /setup-wizard/client

Save client application (Step 4)

POST /setup-wizard/sdk-generated

Mark SDK step as completed (Step 5)

POST /setup-wizard/complete

Complete the wizard and finalize setup

POST /setup-wizard/skip

Skip the wizard (for advanced users)

POST /setup-wizard/reset

Reset wizard state

Authentication Flows

Admin API Key 7 endpoints

Programmable authentication flows: CRUD, per-client assignment, and default-flow seeding.
/admin/realms/:realm/auth-flows
POST /admin/realms/:realm/auth-flows

Create a new authentication flow for a realm

GET /admin/realms/:realm/auth-flows

List all authentication flows for a realm

GET /admin/realms/:realm/auth-flows/:id

Get a single authentication flow by ID

PUT /admin/realms/:realm/auth-flows/:id

Update an authentication flow

DELETE /admin/realms/:realm/auth-flows/:id

Delete an authentication flow

PUT /admin/realms/:realm/auth-flows/:id/assign-client/:clientId

Assign a flow to a client

POST /admin/realms/:realm/auth-flows/seed-defaults

Seed default authentication flows

Risk Assessment

Admin API Key 3 endpoints

AI-powered adaptive authentication: list, inspect, and visualise recent risk assessments and score trends.
/admin/realms/:realm/risk-assessments
GET /admin/realms/:realm/risk-assessments

List recent risk assessments for a realm

GET /admin/realms/:realm/risk-assessments/dashboard

Risk score distribution and anomaly trends

GET /admin/realms/:realm/risk-assessments/:id

Get a single risk assessment by ID

Risk Policies (Continuous Verification)

Admin API Key 7 endpoints

Configure continuous verification risk policies: thresholds, priority ordering, and enable/disable toggles.
/admin/realms/:realmName/risk-policies
POST /admin/realms/:realmName/risk-policies

Create a continuous risk policy in a realm

GET /admin/realms/:realmName/risk-policies

List all continuous risk policies in a realm

GET /admin/realms/:realmName/risk-policies/:id

Get a single continuous risk policy by ID

PUT /admin/realms/:realmName/risk-policies/:id

Update a continuous risk policy

DELETE /admin/realms/:realmName/risk-policies/:id

Delete a continuous risk policy

PATCH /admin/realms/:realmName/risk-policies/:id/toggle

Enable or disable a continuous risk policy

PATCH /admin/realms/:realmName/risk-policies/:id/priority

Update the evaluation priority of a continuous risk policy

Session Risk

Admin API Key 4 endpoints

Per-session risk profiles, distribution dashboard, and on-demand evaluation.
/admin/realms/:realm/session-risk
GET /admin/realms/:realm/session-risk

List session risk profiles for a realm

GET /admin/realms/:realm/session-risk/dashboard

Session risk distribution and trends

GET /admin/realms/:realm/session-risk/:sessionId

Get the risk profile for a single session

POST /admin/realms/:realm/session-risk/:sessionId/evaluate

Trigger an on-demand risk evaluation for a session

Continuous Verification

Admin API Key 12 endpoints

In-session risk events, dashboards, device posture, network context, behavioral biometrics, and per-user summaries.
/admin/realms/:realm/continuous-verification
GET /admin/realms/:realm/continuous-verification/events

List recent continuous risk events for a realm

GET /admin/realms/:realm/continuous-verification/dashboard

Continuous verification dashboard (events + score distribution)

GET /admin/realms/:realm/continuous-verification/events/:id

Get a single continuous risk event by ID

GET /admin/realms/:realm/continuous-verification/session-profiles

List session risk profiles for a realm

GET /admin/realms/:realm/continuous-verification/session-profiles/:sessionId

Get the risk profile for a single session

GET /admin/realms/:realm/continuous-verification/device-posture/:sessionId

Get device posture records for a session

GET /admin/realms/:realm/continuous-verification/network-context/:sessionId

Get network context records for a session

GET /admin/realms/:realm/continuous-verification/behavioral/:userId

Get behavioral biometric samples for a user

GET /admin/realms/:realm/continuous-verification/user/:userId/summary

Get continuous verification summary for a user

POST /admin/realms/:realm/continuous-verification/device-posture

Record device posture from SDK client

POST /admin/realms/:realm/continuous-verification/behavioral/samples

Record behavioral biometric samples from SDK client

POST /admin/realms/:realm/continuous-verification/network-context

Record network context from SDK client

Authorization Policies

Admin API Key 7 endpoints

Define and evaluate ABAC/RBAC policies for fine-grained authorization.
/admin/realms/:realmName/policies
POST /admin/realms/:realmName/policies

Create a policy

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /admin/realms/:realmName/policies

List policies

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /admin/realms/:realmName/policies/:id

Get a policy

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Policy ID
PUT /admin/realms/:realmName/policies/:id

Update a policy

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Policy ID
DELETE /admin/realms/:realmName/policies/:id

Delete a policy

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Policy ID
POST /admin/realms/:realmName/policies/evaluate

Evaluate access against policies

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
POST /admin/realms/:realmName/policies/:id/test

Test a single policy

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Policy ID

Audit Streams

Admin API Key 5 endpoints

Stream audit events to external systems (SIEM, webhooks).
/admin/realms/:realmName/audit-streams
POST /admin/realms/:realmName/audit-streams

Create an audit stream

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /admin/realms/:realmName/audit-streams

List audit streams

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /admin/realms/:realmName/audit-streams/:id

Get an audit stream

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Audit stream ID
PUT /admin/realms/:realmName/audit-streams/:id

Update an audit stream

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Audit stream ID
DELETE /admin/realms/:realmName/audit-streams/:id

Delete an audit stream

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
id uuid Audit stream ID

Protocol Endpoints

OAuth 2.0 Authorization

Public 2 endpoints

Authorization endpoint for the OAuth 2.0 Authorization Code flow with PKCE. Handles SSO session checks and consent.
/realms/:realmName/protocol/openid-connect
GET /realms/:realmName/protocol/openid-connect/auth

Authorization endpoint (code flow)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Query Parameters
Name Type Required Description
response_type string Yes Must be "code"
client_id string Yes Client ID
redirect_uri string Yes Redirect URI (must match client config)
scope string No Requested scopes (space-separated, e.g. "openid profile email")
state string No CSRF protection state parameter
nonce string No Nonce for ID token validation
code_challenge string No PKCE code challenge
code_challenge_method string No PKCE method (must be "S256")
Response

Redirects to login page or directly to redirect_uri with authorization code if SSO session exists.

GET /realms/:realmName/protocol/openid-connect/logout

End-session endpoint (GET)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Query Parameters
Name Type Required Description
id_token_hint string No ID token to identify the session being ended
post_logout_redirect_uri string No URI to redirect to after logout
state string No State to pass back to the post-logout URI
Response

Ends the SSO session and redirects to post_logout_redirect_uri (RP-initiated logout).

Token Endpoint

Client Credentials 1 endpoints

Exchange authorization codes, credentials, or refresh tokens for access tokens and ID tokens. Supports multiple grant types.
/realms/:realmName/protocol/openid-connect
POST /realms/:realmName/protocol/openid-connect/token

Token endpoint (supports multiple grant types)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
grant_type string Yes "authorization_code", "client_credentials", "password", "refresh_token", or "urn:ietf:params:oauth:grant-type:device_code"
client_id string Yes Client ID
client_secret string No Client secret (required for confidential clients)
code string No Authorization code (for authorization_code grant)
redirect_uri string No Redirect URI (must match the authorization request)
code_verifier string No PKCE code verifier
username string No Username (for password grant)
password string No Password (for password grant)
refresh_token string No Refresh token (for refresh_token grant)
scope string No Requested scopes (for client_credentials)
device_code string No Device code (for device_code grant)
Response

Returns { access_token, token_type, expires_in, refresh_token, id_token, scope }.

Token Operations

Bearer Token / Client Credentials 5 endpoints

Introspect tokens, revoke tokens, get user info, and end sessions. Standards-compliant RFC 7662 and RFC 7009 endpoints.
/realms/:realmName/protocol/openid-connect
POST /realms/:realmName/protocol/openid-connect/token/introspect

Token introspection (RFC 7662)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
token string Yes Token to introspect
Response

Returns { active, sub, exp, iat, scope, client_id, ... } or { active: false }.

POST /realms/:realmName/protocol/openid-connect/revoke

Token revocation (RFC 7009)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
token string Yes Token to revoke
token_type_hint string No "access_token" or "refresh_token"
Response

200 OK on success.

POST /realms/:realmName/protocol/openid-connect/logout

End session / logout

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
refresh_token string Yes Refresh token to invalidate
Response

204 No Content on success. Triggers backchannel logout if configured.

GET /realms/:realmName/protocol/openid-connect/userinfo

Get user info from access token

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns user claims { sub, name, email, email_verified, preferred_username, ... }. Requires Bearer token in Authorization header.

POST /realms/:realmName/protocol/openid-connect/logout/backchannel

Backchannel logout (OIDC back-channel)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
logout_token string Yes Signed logout token (OIDC Back-Channel Logout spec)
Response

200 OK on success. Terminates the session referenced by the logout token.

OIDC Discovery

Public 2 endpoints

OpenID Connect discovery document and JSON Web Key Set (JWKS) endpoints. Used by clients to auto-configure.
/realms/:realmName
GET /realms/:realmName/.well-known/openid-configuration

OpenID Connect discovery document

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns OIDC configuration: endpoints, supported grant types, scopes, signing algorithms, claims, and PKCE methods.

GET /realms/:realmName/protocol/openid-connect/certs

JSON Web Key Set (JWKS)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns { keys: [...] } with RSA public keys in JWK format for token signature verification.

OIDC Well-Known

Public 2 endpoints

OIDC discovery document and JWKS endpoints required by the OIDC and OAuth specs.
/realms/:realmName
GET /realms/:realmName/.well-known/openid-configuration

OpenID Connect discovery document

GET /realms/:realmName/protocol/openid-connect/certs

JSON Web Key Set (JWKS)

Device Authorization

Public 3 endpoints

OAuth 2.0 Device Authorization Grant (RFC 8628) for input-constrained devices like smart TVs and CLI tools.
/realms/:realmName
POST /realms/:realmName/protocol/openid-connect/auth/device

Initiate device authorization request

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
client_id string Yes Client ID
scope string No Requested scopes
Response

Returns { device_code, user_code, verification_uri, expires_in, interval }.

GET /realms/:realmName/device

Device verification page (HTML)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Query Parameters
Name Type Required Description
user_code string No Pre-filled user code
Response

Renders HTML device verification page.

POST /realms/:realmName/device

Approve or deny device authorization

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
user_code string Yes User code displayed on device
action enum Yes "approve" or "deny"
username string No Username (required for approve)
password string No Password (required for approve)
Response

Renders success/denied page.

SAML 2.0 IdP

Public 3 endpoints

SAML 2.0 Identity Provider endpoints. Idenplane acts as the IdP, accepting AuthnRequests and returning SAML Responses.
/realms/:realmName/protocol/saml
GET /realms/:realmName/protocol/saml

SSO endpoint (HTTP-Redirect binding)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Query Parameters
Name Type Required Description
SAMLRequest string Yes Base64-encoded, deflated AuthnRequest
RelayState string No Relay state to pass back to SP
Response

Redirects to login page or produces SAML Response for authenticated users.

POST /realms/:realmName/protocol/saml

SSO endpoint (HTTP-POST binding)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Request Body
Field Type Required Description
SAMLRequest string Yes Base64-encoded AuthnRequest
RelayState string No Relay state to pass back to SP
Response

Redirects to login page or produces SAML Response for authenticated users.

GET /realms/:realmName/protocol/saml/descriptor

IdP SAML metadata (XML)

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
Response

Returns SAML IdP metadata XML with entity ID, SSO endpoints, and signing certificate.

Identity Broker

Public 2 endpoints

Handles social login flows with external identity providers. Initiates login redirects and processes callbacks.
/realms/:realmName/broker
GET /realms/:realmName/broker/:alias/login

Initiate social login with an external provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
alias string Identity provider alias (e.g. "google")
Query Parameters
Name Type Required Description
client_id string No Requesting client ID
redirect_uri string No Final redirect URI
scope string No Requested scopes
state string No State parameter
nonce string No Nonce parameter
Response

Redirects to external provider authorization URL.

GET /realms/:realmName/broker/:alias/callback

Handle callback from external identity provider

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
alias string Identity provider alias
Query Parameters
Name Type Required Description
code string Yes Authorization code from external provider
state string Yes State parameter for verification
Response

Processes the external token, creates/links user, and redirects to client redirect_uri with authorization code.

Identity Broker

Public 2 endpoints

User-facing entry points for social login flows brokered through external identity providers.
/realms/:realmName/broker
GET /realms/:realmName/broker/:alias/login

Initiate social login with an external provider

GET /realms/:realmName/broker/:alias/callback

Handle callback from external identity provider

Step-Up Authentication

Bearer (User) 2 endpoints

Initiate a higher-assurance challenge mid-session and verify the response.
/realms/:realmName/step-up
GET /realms/:realmName/step-up/challenge

Initiate step-up authentication challenge

POST /realms/:realmName/step-up/verify

Complete step-up verification

WebAuthn / FIDO2

Mixed — public ceremonies + Bearer for /account 6 endpoints

Passwordless WebAuthn registration and authentication ceremonies, plus self-service credential management.
/realms/:realmName
POST /realms/:realmName/webauthn/register/options

Get registration ceremony options (PublicKeyCredentialCreationOptions)

POST /realms/:realmName/webauthn/register/verify

Verify registration ceremony response and persist credential

POST /realms/:realmName/webauthn/authenticate/options

Get authentication ceremony options

POST /realms/:realmName/webauthn/authenticate/verify

Verify authentication ceremony response

GET /realms/:realmName/account/webauthn/credentials

List current user's WebAuthn credentials

DELETE /realms/:realmName/account/webauthn/credentials/:credentialId

Delete a WebAuthn credential from the current user

SCIM 2.0

Bearer (SCIM provisioning token) 20 endpoints

RFC 7644 SCIM 2.0 surface: schemas, resource types, Users, Groups, bulk operations, and POST search.
/scim/v2
GET /scim/v2/ServiceProviderConfig

Get SCIM Service Provider Configuration

GET /scim/v2/Schemas

Get all SCIM schemas

GET /scim/v2/Schemas/:schemaId

Get a specific schema

GET /scim/v2/ResourceTypes

Get all SCIM resource types

GET /scim/v2/ResourceTypes/:resourceTypeId

Get a specific resource type

GET /scim/v2/:realmName/Users

Get all users (with filtering and pagination)

POST /scim/v2/:realmName/Users

Create a new user

GET /scim/v2/:realmName/Users/:id

Get a user by ID

PUT /scim/v2/:realmName/Users/:id

Update a user (full replacement)

PATCH /scim/v2/:realmName/Users/:id

Patch a user (partial update)

DELETE /scim/v2/:realmName/Users/:id

Delete a user (deprovision)

POST /scim/v2/:realmName/Users/.search

Search users using POST

GET /scim/v2/:realmName/Groups

Get all groups (with filtering and pagination)

POST /scim/v2/:realmName/Groups

Create a new group

GET /scim/v2/:realmName/Groups/:id

Get a group by ID

PUT /scim/v2/:realmName/Groups/:id

Update a group (full replacement)

PATCH /scim/v2/:realmName/Groups/:id

Patch a group (partial update)

DELETE /scim/v2/:realmName/Groups/:id

Delete a group

POST /scim/v2/:realmName/Groups/.search

Search groups using POST

POST /scim/v2/:realmName/Bulk

Execute bulk operations

Hosted Login Flow

Public 15 endpoints

Browser-rendered authentication pages (login, register, MFA, password reset). Render HTML on GET; process form submissions on POST.
/realms/:realmName
GET /realms/:realmName/login

Render login page

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
POST /realms/:realmName/login

Submit login form

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /realms/:realmName/totp

Render TOTP challenge page

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
POST /realms/:realmName/totp

Submit TOTP code

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /realms/:realmName/change-password

Render change-password page

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
POST /realms/:realmName/change-password

Submit new password

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /realms/:realmName/consent

Render consent page

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
POST /realms/:realmName/consent

Submit consent decision

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /realms/:realmName/register

Render registration page

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
POST /realms/:realmName/register

Submit registration form

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /realms/:realmName/verify-email

Verify email via token link

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /realms/:realmName/forgot-password

Render forgot-password page

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
POST /realms/:realmName/forgot-password

Submit forgot-password form

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
GET /realms/:realmName/reset-password

Render reset-password page

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")
POST /realms/:realmName/reset-password

Submit reset-password form

Details
Path Parameters
Name Type Description
realmName string Realm slug (e.g. "master")

Self-Service

Account (Self-Service)

Bearer (User) 10 endpoints

End-user account management: profile, password, TOTP enrollment/disable, GDPR data export, and account deletion.
/realms/:realmName/account
GET /realms/:realmName/account

Get current user's account profile

POST /realms/:realmName/account/profile

Update profile (name, email)

POST /realms/:realmName/account/password

Change password

GET /realms/:realmName/account/totp-setup

Begin TOTP enrollment (QR + secret)

POST /realms/:realmName/account/totp-setup

Verify and complete TOTP enrollment

POST /realms/:realmName/account/totp-disable

Disable TOTP for this account

GET /realms/:realmName/account/data-export

Download GDPR data export (JSON)

GET /realms/:realmName/account/delete-account

Get account-deletion status / grace window

POST /realms/:realmName/account/delete-account

Schedule account deletion

POST /realms/:realmName/account/cancel-delete-account

Cancel a scheduled account deletion

Operations

Health & Metrics

Public 4 endpoints

Health check endpoints for liveness/readiness probes and Prometheus-compatible metrics endpoint for monitoring.
/
GET /health

Liveness check

Details
Response

Returns { status: "ok" } if the server is running.

GET /health/ready

Readiness check (database + memory)

Details
Response

Returns health status for database connectivity and memory heap usage.

GET /health/live

Liveness probe

Details
Response

Returns { status: "ok" } when the process is alive (lightweight probe).

GET /admin/metrics

Prometheus metrics endpoint

Details
Response

Returns Prometheus-formatted metrics (text/plain). Includes HTTP request counts, durations, active connections, and custom Idenplane metrics.