API: Enabling Internal Access to Non-Public Guidelines

This guide explains how to make your organization's non-public MAGICapp guidelines accessible to internal users who don't have MAGICapp accounts.

Overview 

The MAGICapp web component can display non-public guidelines when provided with an access token. Your backend acts as a proxy, authenticating with MAGICapp and passing the token to the web component.

┌───────────────────────┐      ┌─────────────────┐      ┌───────────────────┐
│  User Browser         │ ──── │  Your Backend   │ ──── │    MAGICapp       │
│                       │      │    (proxy)      │      │                   │
│ <magic-recommendation │      │ - Gets token    │      │ auth.magicapp.org │
│  token="...">         │      │ - Renders page  │      │                   │
│                       │      │                 │      │                   │
└───────────────────────┘      └─────────────────┘      └───────────────────┘

Prerequisites 

• An API user in MAGICapp
• Viewer access granted to the API user for the guidelines you want to expose
  
  

Step 1: Grant Viewer Access to Your API User 

1. Log in to MAGICapp
2. Navigate to the guideline you want to expose internally
3. Open the guideline's sharing/permissions settings
4. Grant your API user "viewer" access
5. Repeat for each guideline you want to expose
   

Step 2: Authenticate and Obtain an Access Token 

Your backend should authenticate with Keycloak using your API user credentials. Cache the token and refresh it every 15 minutes.

Step 3: Pass the Token to the Web Component 

When rendering pages that include the MAGICapp web component, include the access token:

<magic-recommendation 
    guideline="guideline-short-code" 
    recommendation="recommendation-id" 
    token="eyJhbG...">
</magic-recommendation>

The web component will use this token when making requests to MAGICapp, allowing it to fetch non-public content that your API user has viewer access to.

Security Considerations 

• Never expose your API user credentials to the browser
• The access token will be visible in the page source
• Only grant viewer access to guidelines you intend to share internally