Our API

Modified on Tue, 20 Aug at 6:12 PM

Our API documentation can be found here: https://api.magicapp.org/swagger-ui/index.html

Public vs. non-public content

You can access Public content through the API without authorisation, but if you would like to access non-public content, you need to register with us to get an API user (client_id and secret). If you are going to use our API actively, we recommend you get an API user, even if you only deal with public content. That way we can contact you if there are pending changes or other important notifications.

API users need access to the correct content

API users show up in the UI as normal users and must be added in permissions to any content that the user will access. Help on how to add users can be found in our help pages. Users that are only going to read data should be set at a Reviewer. Reviewers are not able to modify data.

Be aware: If you give a API user Author or Admin access, they can alter content and permissions, as well as do changes to publishing and settings of a guideline. In many cases, this would not be appropriate.

API users are designed to be used from server side services and NOT in web. By using your API user in a web app or page you'll be expose your credentials. If you expose your credentials, anybody could take them and change your data on you.

Test-environment vs. production environment

We have 2 environments for API-users, one for test and one for production content. You need separate users for these. We would like you to do development and testing in the test environment before we grant you a production user. To get an API-user, contact us on support email (see right side) or email linn@magicevidence.org.

A Quick How-To

1. Authenticate to our identity provider (idAM) to get an Bearer token usign you credientals.

curl --location 'https://auth-test.magicapp.org/auth/realms/magicapp/protocol/openid-connect/token' \
       --header 'Content-Type: application/x-www-form-urlencoded' \
       --data-urlencode 'client_id=<CLIENT_ID>' \
       --data-urlencode 'client_secret=<SECRET>' \
       --data-urlencode 'grant_type=client_credentials'

This example is for our test enviroment. hostname should be api.magicapp.org for prod
Tokens have a short life span of 24 hours.

2. Pass your Bearer token in Authorization header.

curl --location 'http://localhost:8080/api/v1/guidelines' \
       --header 'Authorization: Bearer <token>'