Obtain an admin access token by POSTing to https://{host}/realms/master/protocol/openid-connect/token with grant_type=client_credentials (or password) and credentials for an admin client or user.
Create a new realm by POSTing a RealmRepresentation JSON body to POST /admin/realms; include at minimum the realm name, enabled true, and any initial settings.
Create a client within the realm by POSTing a ClientRepresentation to POST /admin/realms/{realm}/clients; set clientId, protocol (openid-connect), redirectUris, and publicClient or serviceAccountsEnabled as appropriate.
Retrieve the generated client secret for confidential clients by calling GET /admin/realms/{realm}/clients/{clientUuid}/client-secret.
Add protocol mappers to the client or client scope using POST /admin/realms/{realm}/clients/{clientUuid}/protocol-mappers/models to customize token claims.
Assign realm roles or composite roles to service accounts or users via the role-mappings sub-resource on the user or service account endpoint.
Known gotchas
The admin access token is short-lived; long-running automation scripts must refresh it before each batch of API calls or handle 401 responses with token refresh logic.
POSTing to /admin/realms to create a realm returns 201 with no body on success; the new realm's admin endpoints are then available under /admin/realms/{newRealmName}.
Client UUIDs (used in API paths) differ from clientId (the human-readable name); always look up the UUID via GET /admin/realms/{realm}/clients?clientId={clientId} before making client-specific calls.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp