API: Enabling internal access to non-public guidelines (technical documentation)

Modified on Tue, 17 Nov at 10:02 AM

About this article

This article is intended for technical teams responsible for website integrations and software development.


This guide explains how to make non-public MAGICapp guidelines available to internal users who do not have MAGICapp accounts. It describes how to authenticate using an API user account and configure access tokens for use with MAGICapp web components.


Looking for general information about sharing MAGICapp content?

See:


Looking for general API integration guidance?

See API: Using the MAGICapp API (technical documentation) for information about API user accounts, authentication, permissions, and direct API integrations. This article focuses specifically on enabling access to non-public guideline content.


Using widgets to display content?

See Embeddable widgets for website integration (technical documentation) for an overview of MAGICapp's web components and related widget documentation.


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


If you have any queries about our API, please contact support@magicevidence.org


Last updated: 17 November 2026

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article