API Reference

REST API Reference

Complete reference for all AuthMe REST API endpoints. 111 endpoints across 24 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 9 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: "authme")
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.

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 9 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.

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 7 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.

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 3 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.

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 12 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.

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 3 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.

Client Scopes

Admin API Key 14 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.

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. AuthMe 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 2 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.

Brute Force Protection

Admin API Key 2 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.

Admin Authentication

Public / Admin Token 2 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.

Protocol Endpoints

OAuth 2.0 Authorization

Public 1 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.

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 4 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.

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.

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. AuthMe 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.

Operations

Health & Metrics

Public 3 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 /metrics

Prometheus metrics endpoint

Details
Response

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