1.Introduction

At present, the following types of authentication are supported:

• API key, suitable for local applications (e.g. a Jupyter notebook), employed directly by the user
• OAuth2, for web applications, where third-party users will need to get authenticated

This short manual provides step-by-step instructions on how to configure the desired API access:

• Accessing the portal
• Obtaining an API key
• Retrieving a forgotten API key
• Configuring OAuth2

2.Accessing the API portal

• Make sure you can log in successfully at H2020 CHARISMA. If you encounter any problems, please write to `support@ideaconsult.net`.
• Go to https://api.ideaconsult.net/ and click the `LOGIN link` in the top right corner

• Click on the red “Sign in with data.enanomapper.net” button.
• A new browser window, “Login with your data.enanomapper.net credentials”, will open.
• Enter your username and password in this new, small window, and click “LOG IN”.

• If you get a red message “Wrong username or password”, make sure that you are entering the correct username and password. If the problem persists, please write to support@ideaconsult.net.
• Normally, the small window should disappear and you should see the following page, with the “Charisma_backup aggregated search“ box.

3.Obtaining an API key

• On the API portal main page (see previous section), click the Charisma_backup box.
• You should now see the available subscription plans for the API, with different levels of access and different authentication. Select the “API KEY” plan by clicking on its “SUBSCRIBE” button.
• Make sure to also check the API documentation from the “Documentation” link.

• The next screen shows the subscription options. Click in the “Select an application...” field and choose “Default application” from the drop-down list.
• The “SUBSCRIBE” button should light up. Click on it.

• If everything went well, a green notification should appear in the lower right corner.
• Scroll down to find the unique API key that has been issued to you. You can copy it to the clipboard by clicking on the indicated button. Please note that the example provided below the API key may be empty or not working, due to limitations in the current version of the API portal. This will likely be fixed in the future.

• You can try the key in the demo notebooks, in section “Aggregated search” of the tutorial.
• You can also do a quick test with curl, which in the example here is also supplemented by jq:

Keep your API key secret! It gives the same level of access to the data as your password.

4.Retrieving a forgotten API key

If you forget your API key, do the following steps to retrieve it:

• Open https://api.ideaconsult.net and log in if necessary (see “database API access” above 1 & 2).
• Click on the person icon in the top right corner and choose “Applications” from the menu that will pop up.
• From the “Applications” screen, choose “Default application”. NB: If you have created different apps, choose the one that you used to subscribe.

• From the application screen, click on the key icon on the left.
• Now click on the respective API and the next screen will show your API key.

5.Configuring OAuth2

The main supported OAuth2 setup is:

• the client must use the Authorization Code Grant flow
• an allowed redirect URI or a list of such URIs must be provided
• the redirect URI(s) must use https; plain http is not allowed
• redirect URIs with patterns/wildcards are not allowed
• the client may not request other scopes than:

• the access tokens will be valid for:

• the refresh tokens will be valid for 604800 seconds (7 days)
• it is expected that the client follows the OAuth 2.0 Security Best Current Practice

Other setups may be possible on request:

• Please contact support@ideaconsult.net to discuss them.
• The authorization server OAuth2 API documentation is available here
• The authorization server OAuth2 API is exposed at: https://idp.ideaconsult.net/auth/idea-api/oauth

6.OAuth2 client registration

Log in to the API portal as described in the section “Accessing the API portal” earlier in this document.

Send the following information to support@ideaconsult.net:

• client description (if not discussed previously)
• preferred client_id name (the final name will have some random string appended)
• whether the client will use refresh tokens (and require the offline_access scope)
• an allowed redirect URI or a list of such allowed redirect URIs

After the client is registered and you get back the final client_id and the client_secret, subscribe to the API.