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
- Log in to MAGICapp
- Navigate to the guideline you want to expose internally
- Open the guideline's sharing/permissions settings
- Grant your API user "viewer" access
- 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
Feedback sent
We appreciate your effort and will try to fix the article