Using the MAGICapp API

API Documentation

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

Public content

Unauthenticated API users can only access publicly available content. 

Non-Public content

If you need  to access your organization’s non-public content through the API, your organisation needs to make a request for an API User Account.

Non-public content is content that customers have created in MAGICapp that has not been set to be public content, e.g.:

• Drafts of guidelines - these are never public
• Published guidelines not set to be public, which means they are only visible to users who are specifically given access permissions. 

API access to non-public content is restricted to use by the API User Account for that organisation

The permissions model

To protect customer data, you will need an API User Account to access non-public content. Currently, we allow each customer organization to have one API User Account for each of our environments (test environment and production environment). Details on obtaining an API User Account can be found below. 

Once your organization has an API User Account, you will need to grant the API User Account access to the guideline content you want to access through the API. 

The API User Account will not be able to access any content by default. 

The same permissions model applies to both regular user accounts and API user accounts, so access is granted in the same location as adding an author to the guideline. Navigate to the permissions area for the guideline in question, but instead of selecting an author’s name you select the check box for “Allow the API User Access”. If you uncheck the box, you remove access. 

By default, the API User Account is set to have the permission level of author. This allows read and write permissions. You can change the permission level using the drop down, e.g. if you want it to be read only, change it to “reviewer”. 

Please think carefully about these permissions. If you give the API User Account author permission level then it is able to edit your content and, similarly, if you give the API User Account admin access, it will be able to change permissions, customisations and other administrative features of the guideline. 

MAGICapp environments

We have two environments for MAGICapp, a test environment and a production environment. The user permissions for the different environments are completely separate, so you cannot use credentials from one environment to access the other. 

We require you to do development and testing in the test environment before working with the production environment.

Obtaining and using an API User Account for your organization

Please complete this form to request an API User Account for your organization: API User Account Request Form. 

API users are designed to be used from server-side services. Do not use your API User Account in a web app or page as you will expose your credentials, and anybody could take them and use them to access / edit your data. 



Authenticating to our identity provider 

You need to authenticate to our identity provider (idAM) to get a bearer token using your credentials.

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

• This example is for our test environment. The hostname should be api.magicapp.org for the production environment.
• Tokens have a short life span of 24 hours.

Pass your Bearer token in Authorization header.

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

Terms and conditions of API User Accounts

1. Using the API: You're welcome to use our API as long as you follow the rules. Keep things legal, ethical, and respectful. No bad stuff!
2. Security: If we provide you with credentials, keep them safe! Don't share them with others.
3. Fair Usage: Please use our API responsibly. We do not set specific rate limits, we just ask that you are sensible and don’t overload it, so everyone gets a smooth experience.
4. Changes & Updates: We might update or modify the API from time to time. We'll try to keep you in the loop!
5. No Guarantees: We do our best, but we can't promise the API will always be perfect.
6. Play Nice: If you misuse the API, intentionally or unintentionally, we might have to block your access.
7. By using the MAGICapp API, you agree to these terms. Have fun building!