Do you want an overview of our solutions, customer cases and contact details?


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

Prerequisites

 Prerequisites
  • Installed Hermod, see here.

Step-by-step instruction

 Edit configuration file

To configure Hermod, do the following:

  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
    mydir/ 
    |-- 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

    Application.yml is a link to cod-hermod.ymlApplication.yml is the actual file used by the server. 

  3. Open a browser and go to the following URL, using a unique <myclientid>:

    Example: Generate client URL
    http://localhost:20400/<contextPath>/<uriBase>/util/generateclient/<myclientid>

    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
     # X-Api-Key: a2Fyb2xpbjpmZDA0ZGUyZjFlNTU0NGIyOTE1ZDFhNjUwOThjNDkwNjM3YTA3MTVmNWM5ODQzNDU5ZjA1ZGZjMjk4MzQyOTM2 
    - 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
    	# Optional: username and password to be supplied for basic authentication to the content provider
        contentProviderBasicAuth: user:pwd
    	# Optional: The URL to the content provider API
        contentProviderUrl: http://myprovider/getcontent

    X-API-Key, which is the base64-encoded value of clientId:key, is the key you need to configure in clients, such as Nexus PRIME

    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. If visual data is to be fetched from an external content provider:
    Edit contentProviderUrl to point to the Content provider API.
    Also edit user and pwd if the content provider requires basic authentication.
  7. 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.

This article is valid from Hermod 2.4.

Related information