Page tree
Skip to end of metadata
Go to start of metadata

This article describes how to add a new API user in Hermod to get a unique API key for authentication to the API.

Expand/Collapse All


  • Installed Hermod, see here.

Step-by-step instruction

 Edit configuration file
  1. Navigate to the top-level directory where docker-compose.yml is located. The configuration file should then be found in a config/ directory.

    Example: File structure
    |-- cacerts 
    |-- certificates 
    |-- config 
    |-- application.yml -> cod-hermod.yml 
    | `-- cod-hermod.yml 
    `-- docker-compose.yml
  2. Open the configuration file for editing:

    Example: Command to edit configuration file
    vi config/cod-hermod.yml
  3. Open a browser and go to the following URL, using a unique <myclientid>:

    Example: Generate client URL

    Find port number

    All requests below are triggered from the host itself, thus localhost is used.

    Please note that the port number (20400 in the example above) might have been assigned a different value via docker. To find out the current port number, type the following command:

    docker ps | grep hermod_hermod
  4. Copy the content from the resulting web page and paste it into the allowedClients section of the configuration file.

    Example: Generate client
    - clientId: <myclientid> 
    	key: fd04de2f1e5544b2915d1a65098c490637a0715f5c9843459f05dfc298342936 
    	# Optional username:password to be supplied for basic authentication in callbacks 
    	callbackBasicAuth: username:password 
    	# The callback URL base for this specific client 
    	callbackUrl: http://localhost:20400/hermod/rest

    Make sure not to add extra spaces in the configuration file, since the .yml file format is space sensitive.

  5. Edit callbackUrl to receive the callbacks from the Hermod API.
    Also edit username and password if the callback URL requires basic authentication.

  6. Save and exit the configuration file.

 Refresh configuration and test API key
  1. Refresh the configuration:

    Example: Refresh configuration
    curl -X POST http://localhost:20400/<contextPath>/refresh
  2. Test the new key by sending a request using curl (set THE-NEW-KEY below):

    Example: test API key
    curl -w%{http_code} -X POST \
      http://localhost:20400/<contextPath>/<uriBase>/command/ping \
      -H 'cache-control: no-cache' \
      -H 'content-type: application/json' \
      -H 'x-api-key: THE-NEW-KEY' \
      -d '{
      "commandHeader" : {
        "to": ["api-test"]
  3. Check the response.
    1. If you get a 403 response, you have the wrong API key.
    2. If you get a 404 response, then you have the correct API key. A 404 response means that the user api-test isn't found, which is expected at this point.

Related information