Developer Portal

Developer Accounts

If you want to develop a MIDATA plugin, a mobile app or backend service you need a developer account. Please click on “Sign Up” on the top of the developer login page and submit your request for an account. Please note that the issuing of a developer account is conditioned to the pre-existence of a contract and/or a partnership agreement between MIDATA and the requesting party.

Using the developer account you can register a new plugin or mobile app and manage it.

Your developer account is distinct from your normal account holder account which you may also have. You can have a developer account with the same email as an account holder account. In order to log in you need to navigate to the developer portal first.

If you are developing a plugin you can test your development version running on your own computer using the developer portal. When you are done with development you need to send the code to us for review and final integration.

NOTE: After your developer account got enabled, you will receive an email.

After sign up or login these topics are available from the main menu at the top:

  • Your applications : View and manage your applications or create new ones.
  • Sandbox : An empty dashboard where you can test your plugins.
  • Test Records : The record tree of all records stored for this developer account. For debugging purposes.
  • Test User : Create additional users that may have another role for testing your applications.

Test User Accounts

As developer you may register test accounts with other roles than developer. These test accounts do not need to represent really existing people but are just for testing your application. They are tied to your developer account. If you are developing a plugin these test accounts will use your local installation of the plugin.

Click on „Test Users“ in the top menu to view a list of all test users created by you.

Click on „Register Account Holder“, „Register Health Provider“ or „Register Researcher“ in order to register a new test user. You will be redirected to the „normal“ registration page for that role. The user account created this way will be immediately available and no welcome mail will be sent to the used email address.

Creating an new “app”

Before you connect your app with MIDATA it first has to be registered.

Each application needs to have an internal name that is used by the platform to identify that application. The application developer also needs to specify a public name for the marked place and a textual description, that describe what it does. For OAUTH2 login of your app you need to define the possible redirect URIs. Also a secret key needs to be entered that is known to the mobile app but should not be made public.

To register your app, log in into your developer account. On the “Your Applications” page click on “Register a new plugin” and fill out the form. Choose “Application (Smartphone/Web)” as “type” of the plugin.

Please fill out the various input fields. You can also change the settings for your app later.

Click on “Submit” when you are done. The description of the fields are below.

Internal Name

This name is internally used to identify your app. Should be a valid identifier (a-z, A-Z, 0-9, _). The name must be system wide unique. If you want to use SMART on FHIR authentication the Internal Name must match the client_id parameter your app will send during authentication. For the MIDATA API it must match the appname parameter during authentication.

Target Role

Is your app for a specific user role only? Otherwise choose ‘Any Role’.

If you select “any role” a role selection picklist will be shown on the OAuth login page. If you select “Researcher” a research project selection picklist will be shown on the OAuth login page.

Type

Must be set to „Application (Smartphone/Web)“ for an external app.

Requirements

Please select any requirements your app has in regards to the user that uses the app. The MIDATA platform itself may have default requirements. Please keep in mind that these may change in the future. Currently these requirements are available: (Requirements marked in bold are currently required by the platform itself)

  • Email address of user must be known to the platform
  • Email address of user must have been verified - If selected the app can only be used after the user has confirmed his email address. Otherwise he has one day time to do so.
  • Mobile phone number of user must be known to the platform - The platform will ask for the number if it is not already known
  • Mobile phone number of user must have been verified - The user must do 2FA with his mobile phone number once to prove the correctness of the number
  • 2-Factor Authentication on login - The APP login may be protected by 2FA
  • Post address of user must be known to the platform - The user will be asked for his address if it is not already known to the platform
  • Post address of user must have been verified - Verification of the address by entering a code send to the user by letter
  • The date of birth of the user must be known - The user will be asked for his birth date
  • ID card of users must have been verified - Currently not supported
  • User must be member of the cooperative - Currently not supported
  • Account must have been unlocked by a MIDATA administrator

Name

The name of your app that will be presented to the end user. (International Name)

Description

A description of your app. This may be presented as part of the OAuth2 authorization to the end user. It may also be added to lists of available MIDATA apps should this ever be added as feature to the platform. (International Description)

Organization Name

If the app is provided by an organization enter the name of the organization here.

Publisher

If the app is published by a 3rd party enter the name of the publishing organization here.

Multi Language Support

Name and Description may also be provided in other languages. If no translation for the users language is available the international version from above will be used. First select the desired language then enter the localized name and description.

Tags

This is currently ignored for apps.

Write Access

Please select if and what data your app may write.

Possible choices are:

  • No data may be written
  • Existing data may be updated
  • Data covered by consent may be written or updated
  • Any kind of data may be written or updated

Resharing

Your application may create FHIR Consent Resources in order to propose sharing data with other people. If you check this checkbox your application may even create *active* consents if only data is shared that is accessible by the app anyway.

User Search

Check this checkbox if your application uses the FHIR endpoint /fhir/person to search for other people using your app.

If this checkbox is not checked a search on the /fhir/person endpoint will return account holders that have explicitely marked their account as searchable.

Application Secret

Your app will need this ‘secret’ during login. The Application Secret is required for authentication with the MIDATA API and for SMART on FHIR confidential launch. You can choose the secret freely. IMPORTANT: When you develop third party apps, you should not set a secret. The app will not be able to protect this secret. For more information about how to and when to use the secret, can be found in the smart authorization guide.

Redirect URI (optional, required for OAuth2 login)

The Redirect URI is used for the SMART on FHIR public launch sequence. The redirect URI must match the redirect URI your app will provide during authentication.

Code for Registration

If this field is filled out any user who wants to use your application needs to enter this code during OAuth login. Use this feature to restrict your apps use to an event like on a fair.

After registration you need to specifiy the access filter for your application. The access filter defines which data your application needs to access.

Creating a new plugin or service

Each application needs to have an internal name that is used by the platform to identify that application. The application developer also needs to specify a public name for the marked place and a textual description, that describe what it does.

To register your plugin, log in into your developer account. On the “Your Applications” page click on “Register a new application” and fill out the form. Click on “Submit” when you are done.

Internal Name

This name is internally used to identify your plugin. Should be a valid identifier (a-z, A-Z, 0-9, _).

The name must be system wide unique and is used as directory name to store your plugin files on the server.

Target Role

Is your plugin for a specific user role only? Otherwise choose ‘Any Role’. The plugin will be only offered to be used for users having the selected role.

Application Type

Select the type of plugin you want to create. Select

  • Service if you are writing a backend service that does not have any frontend
  • OAuth1 if your plugin does requests to an external OAuth1 API
  • OAuth2 if your plugin does requests to an external OAuth2 API
  • Plugin otherwise

Requirements

Please select what requirements your plugin has in regards to the user account that will use it. Please note that the platform itself might have its own separate requirements or policies.

Please select what is important for your plugin.

Name

The name of your plugin that will be presented to the end user. (International Name)

Description

A description of your plugin. This is displayed to the user in the portal if the user wants to add a tile to the dashboard.

Tile Name

Name of the tile for your plugin on the dashboard.

Organization Name

Name of the organization you belong to.

Publisher

If the plugin is published by a 3rd party enter the name of the publishing organization here.

Multi Language Support

Name, Description and Tile Name may also be provided in other languages. If no translation for the users language is available the international version from above will be used. First select the desired language then enter the localized name and description.

Tags

Categories for this plugin.

URL

enter the relative base URL of your plugin. The default value for plugins created using the template provided by MIDATA is

dist/index.html#?authToken=:authToken

Dashboard Tile URL

if your plugin has a preview tile you may enter the base URL for that tile here. This is optional.

Default Dashboard

Enter “config” if you write an import plugin otherwise leave empty.

Write Access

Please select if and what data your plugin may write.

Possible choices are:

  • No data may be written
  • Existing data may be updated
  • Data covered by consent may be written or updated
  • Any kind of data may be written or updated

Resharing

Your plugin may create FHIR Consent Resources in order to propose sharing data with other people. If you check this checkbox your application may even create active consents if only data is shared that is accessible by the app anyway.

OAuth 1

For Plugins using Oauth 1 import. These additional parameters must be filled out:

  • Authorization URL
  • Access Token URL
  • Consumer Key
  • Consumer Secret
  • Request Token URL

OAuth2

For Plugins using Oauth 2 import. These additional parameters must be filled out:

  • Authorization URL URL of login page of external OAuth2 service to connect to
  • Access Token URL URL of OAuth2 token endpoint{end}
  • Consumer Key Consumer key issued to this plugin by external service
  • Consumer Secret Consumer secret issued to this plugin by external server
  • Scope Parameters String to send as „scope“ parameter during login

Table of contents