How to create a new realm with the Keycloak REST API?

In this blog post I want to show, how to create a new realm with Keycloak REST API , because later I want to automate the Keycloak realm creation for a workshop using curl in a bash script.

The reason of that blog post is, that the information in the REST API documentation wasn’t detailed enough for me. The image shows what I found first in the Keycloak REST API documentation .


In common it’s very simple to use the Keycloak REST API. For more details see in my blog post Getting started to secure a simple Java Microservice with Keycloak, MicroProfile and OpenLiberty.

First you need a bearer authorization token for an administration user and with that token you create a new realm using the realm json exported before.

Here is what I found:

I used POSTMAN to check it out. These are the steps I did in POSTMAN.

1. Authorize user for administrative tasks

These are the values I used for the REST API POST request to get the access_token.
In the following section you see the URL structure, the needed header and body with the values I used and also the response of the request.

Key Value
Content-Type application/x-www-form-urlencoded
  • Body:
Key Value
grant_type password
client_id admin-cli
username admin
password admin
  • Response:

The image shows request response with the access_token, I used for the next realm creation request.


2. Create the realm

These are the values I used for the POST request to get the new realm.
In the following section you see the URL structure, the needed header and body with the values I used and also the response of the request.

  • RESTful command: POST
  • URL: https://KEYCLOAKSERVER/auth/admin/realms
  • Header:
    Copy the access_token value and past the token value into the authorization.
Key Value
Authorization bearer access_token value
Content-Type application/x-www-form-urlencoded
  • Body:
raw JSON(application/json)

The image shows the body with the realm json, I used to create the new realm.


  • Response:

The image below shows, now I got the 201 response and the new realm was created.


I verified the creation in the Keycloak server instance, and you see in the following image “it worked”.


Additional resources

Because of the often requests in the comments. Here are the links to the example I used and a YouTube video I made:

I hope this was useful for you and let’s see what’s next?



Some of my related blog posts:

#IBMDeveloper,  #Keycloak, #RESTAPI

21 thoughts on “How to create a new realm with the Keycloak REST API?

  1. a says:

    Your article was very helpful.
    We want to create a realm by receiving a token using the master realm’s matser-realm client.
    At this point, I get a 403 unauthorized. But, it works well with the token of admin-cli client.
    Do you know how to create a realm with the master-realm’s client token?

    Liked by 1 person

  2. G BHANU Prakash says:

    I have an end to end automation on Keycloak API with Curl commands.Can u suggest any Curl commands to create client with protocol mapper.


    • thomassuedbroecker says:

      Hi Bhanku,

      Hmm no … I can only share my bash script for the automation I did, maybe that helps a bit …


      # Set the needed parameter

      echo "------------------------------------------------------------------------"
      echo "Your INGRESSURL for Keycloak: https://$INGRESSURL"
      echo "------------------------------------------------------------------------"
      echo ""

      # Get the bearer token from Keycloak
      echo "------------------------------------------------------------------------"
      echo "Get the bearer token from Keycloak"
      echo "------------------------------------------------------------------------"
      echo ""
      access_token=$( curl -d "client_id=$CLIENT_ID" -d "username=$USER" -d "password=$PASSWORD" -d "grant_type=$GRANT_TYPE" "https://$INGRESSURL/auth/realms/master/protocol/openid-connect/token" | sed -n 's|.*"access_token":"\([^"]*\)".*|\1|p')

      # Create the realm in Keycloak
      echo "------------------------------------------------------------------------"
      echo "Create the realm in Keycloak"
      echo "------------------------------------------------------------------------"
      echo ""

      result=$(curl -d @./quarkus-realm.json -H "Content-Type: application/json" -H "Authorization: bearer $access_token" "https://$INGRESSURL/auth/admin/realms")

      if [ "$result" = "" ]; then
      echo "------------------------------------------------------------------------"
      echo "The realm is created."
      echo "Open following link in your browser:"
      echo "https://$INGRESSURL/auth/admin/master/console/#/realms/quarkus"
      echo "------------------------------------------------------------------------"
      echo "------------------------------------------------------------------------"
      echo "It seems there is a problem with the realm creation: $result"
      echo "------------------------------------------------------------------------"

      Greetings, Thomas


  3. G BHANU Prakash says:

    Thank you for your script. Its working manually. When i do the curl, i am getting 401 unauthorized.
    It seems there is a problem with the realm creation: {“error”:”HTTP 401 Unauthorized”}

    I used below script:-

    access_token=$( curl -d “client_id=$CLIENT_ID” -d “username=$USER” -d “password=$PASSWORD” -d “grant_type=$GRANT_TYPE” “http://$INGRESSURL/auth/admin/realms/master/protocol/openid-connect/token” | sed -n ‘s|.*”access_token”:”\([^”]*\)”.*|\1|p’)

    result=$(curl -d @./bo_realm-realm.json -H “Content-Type: application/json” -H “Authorization: bearer $acess_token” “http://$INGRESSURL/auth/admin/realms”)

    Liked by 1 person

  4. Warlord says:

    This was very useful, thanks for the post.

    I thought it might be useful to others to grab the JSON required to create a realm by querying it from another using GET.

    Using the VSCode api rest client I make the calls like this:

    # @name get_token

    POST https://sso.{{$dotenv HOST}}.{{$dotenv DOMAIN}}/auth/realms/master/protocol/openid-connect/token HTTP/1.1
    Content-Type: application/x-www-form-urlencoded

    grant_type=password&client_id=admin-cli&username=admin&password={{$dotenv KEYCLOAK_PASSWORD}}

    # @name show_realm
    @access_token = {{get_token.response.body.access_token}}
    GET https://sso.{{$dotenv HOST}}.{{$dotenv DOMAIN}}/auth/admin/realms/master
    Content-Type: application/json
    Authorization: bearer {{access_token}}

    Liked by 1 person

  5. mhaverick says:

    Thanks for the post very helpful, Keykloak need more resources and example for it API ! Just something, Part 2 give an header “Content-Type : form encoded”, but you describe a JSON format to create the realms (and you precise it very well in the next line !).
    Just saying 😉 Thanks mate.


  6. Bruno says:

    Hey Thomas, nice post, really helpful. I’m new with Keycloak and this post is helping me to automate the setup and I’ve a question if may I ask, I’m using Keycloak as Key Manager of WSO2 but if I create an user on another Realm other than Master, I get “401 Unauthorized” from Keycloak, Do you have any idea on where to start to look?.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.