Skip to main content
Embedded analytics lets you deliver personalized Evidence reports to your customers directly within your application. Each user sees only their data, and the reports match your application’s design.
Embedded Analytics is available on the Enterprise Plan. Contact us to upgrade
What you can do:
  • Match your brand with custom themes
  • Show different data to each user based on their permissions
  • Embed specific pages from your Evidence project
  • Support multiple languages
Requirements:
  • Your development team will need to add a backend endpoint to request embed URLs from the Evidence Embed API
  • Each embedded report loads in an iframe on your page

​
How It Works

The Evidence Embed API allows you to embed Evidence reports directly inside your own application using iframe embedding with secure authentication. The embed process uses a two-step authentication flow:
  1. Server-side: Your backend requests an embed URL from the Evidence Embed API for a specific user
  2. Client-side: The embed URL is loaded in an iframe, establishing an encrypted session in the user’s browser
The embed URL contains a nonce (single-use token) in its path. User attributes are encrypted using JWE and never exposed.

​
Authentication

  • Single-use URLs: Each embed URL contains a nonce that expires in 2 minutes and can only be used once
  • JWE Encryption: User attributes and metadata are encrypted using JSON Web Encryption
  • Row Level Security: Integrates with access control rules to filter data by user

​
Getting Started

1

Set Up and Publish a Page

Create the Evidence page you want to embed and publish your project. The page must be published before it can be embedded.Make note of the page’s:
  • Page ID: Found in page settings
  • Path: The full path to the page (e.g., org_id/project_name/page_name)
2

Create RLS Rules (Optional)

If you need to filter data based on user attributes, set up row-level security rules in your Access Settings.Define which user attributes will be used to filter data (e.g., employee_id, region, department).
3

Create an API Key

Navigate to your Organization Settings and create a new API key for the Evidence Embed API. Store this key securely - you’ll need it to authenticate API requests.
4

Test the API

Test the Evidence Embed API using curl to verify your setup. Replace YOUR_API_KEY, YOUR_PAGE_ID, and YOUR_PAGE_PATH with your values:
curl https://management.evidence.studio/v1/embedded \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "userId": "test_user_123",
    "pageId": "YOUR_PAGE_ID",
    "path": "YOUR_PAGE_PATH",
    "ttl": 3600,
    "attributes": [
      {
        "key": "employee_id",
        "value": 1102
      },
      {
        "key": "region",
        "value": "Canada"
      }
    ],
    "cookieless": true,
    "testMode": true
  }'
The API will return a response with a url field. Copy this URL and open it in an incognito/private browser window to verify the page loads correctly.
Use cookieless: true when testing to avoid cookie-related issues in development.
5

Backend Integration

Add an endpoint to your backend server that requests embed URLs for authenticated users.Example:
app.post('/api/embed-report', async (req, res) => {
  const { userId, pageId, path } = req.body;
  
  // Verify user is authenticated (use your auth system)
  if (!req.user) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  // Fetch user attributes from your database
  const userAttributes = await getUserAttributes(userId);
  
  // Request embed URL from the Evidence Embed API
  const response = await fetch('https://management.evidence.studio/v1/embedded', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.EVIDENCE_API_KEY}`
    },
    body: JSON.stringify({
      userId: userId,
      pageId: pageId,
      path: path,
      ttl: 3600,
      attributes: userAttributes,
      cookieless: true
    })
  });
  
  const data = await response.json();
  res.json({ embedUrl: data.url });
});
Store your API key securely on the server and never expose it to the client.
6

Frontend Integration

Request an embed URL from your backend endpoint and use it to load the report in an iframe:
<iframe
  src="https://management.evidence.studio/v1/embedded/2pgHuWMjErQOoMXkxxGME6uEVhNfY35TLYDvTYEylWiIt0HSIrdjrfAZ7Kk4n25czdYh86bQ4u"
  width="100%"
  height="600"
  frameborder="0"
  allowfullscreen>
</iframe>
Use the full URL returned from your backend in the iframe’s src attribute.

​
API Reference

​
POST /v1/embedded

Creates a secure embed session and returns a single-use embed URL.

​
Request Parameters

ParameterTypeRequiredDescription
userIdstringYesUnique identifier for the user viewing the report
pageIdstringYesUUID of the specific page to embed
pathstringYesPath to the page (e.g., “org_id/project/page-name”)
ttlnumberNoTime-to-live in seconds (default: 3600, max: 604800)
attributesarrayNoUser attributes for row-level security
cookielessbooleanNoEnable cookieless mode (default: false)
testModebooleanNoEnable test mode (default: false)
languagestringNoDisplay language code (e.g., “en”, “fr”)

​
User Attributes

User attributes are used with row-level security rules to filter data. Evidence supports rich attribute types: 
{
  "attributes": [
    {
      "key": "employee_id",
      "value": 1102
    },
    {
      "key": "region",
      "value": "Canada"
    },
    {
      "key": "departments",
      "value": ["Sales", "Marketing"]
    },
    {
      "key": "zone_ids",
      "value": [193, 992, 19183]
    },
    {
      "key": "isAdmin",
      "value": false
    }
  ]
}
Supported Value Types:
  • Strings: "Canada", "Sales"
  • Numbers: 1102, 42.5
  • Booleans: true, false
  • String Arrays: ["Sales", "Marketing"]
  • Number Arrays: [193, 992, 19183]
Attributes can be included in embed requests even if they’re not currently mapped to an RLS rule.

​
Response

{
  "url": "https://management.evidence.studio/v1/embedded/2pgHuWMjErQOoMXkxxGME6uEVhNfY35TLYDvTYEylWiIt0HSIrdjrfAZ7Kk4n25czdYh86bQ4u"
}
The url field contains a single-use embed URL with an embedded nonce. Use this full URL in your iframe’s src attribute.

​
GET /v1/embedded/

Loads the embedded report when accessed via iframe. The nonce in the URL path is validated and can only be used once.

​
Configuration Options

​
Time-to-Live (TTL)

Control how long an embed session remains valid: 
{
  "ttl": 86400  // 24 hours in seconds
}
  • Minimum: 60 seconds (1 minute)
  • Maximum: 604800 seconds (7 days)
  • Default: 3600 seconds (1 hour)
Embed URLs are valid for 2 minutes and can only be used once. The TTL parameter controls the session duration after the URL is accessed.

​
Cookieless Mode

Enable cookieless mode for privacy compliance: 
{
  "cookieless": true
}
When enabled, the embed session will not use browser cookies for authentication. Use cases include:
  • GDPR and privacy compliance requirements
  • Third-party cookie restrictions
  • Environments where cookies are blocked

​
Language Support

Embed reports in different languages if your Evidence project supports translations: 
{
  "language": "fr"  // French
}

​
Test Mode

Use test mode for development and debugging on localhost 
{
  "testMode": true
}
Test mode should only be used in development environments. It may bypass certain security checks.

​
Implementation Guidelines

​
Security

  1. Protect your API key: Make Evidence Embed API requests from your backend server only, never from client-side code
  2. Set appropriate TTLs: Use the shortest TTL that meets your requirements
  3. Validate users: Verify user authentication before requesting embed URLs
  4. Apply RLS rules: Use row-level security to filter data appropriately

​
Performance

  1. Pre-generate URLs: Request embed URLs before the user navigates to the page to reduce perceived loading time
  2. Session refresh: Implement logic to refresh sessions before they expire for long-running user sessions

​
Error Handling

  1. Handle expired sessions: Implement logic to request new embed URLs when sessions expire
  2. Provide feedback: Show loading states and clear error messages
  3. Handle edge cases: Test behavior with expired URLs, network failures, and long-running sessions

​
Frequently Asked Questions

Yes, request a separate embed URL for each page you want to embed.
The iframe will show an error. Request a new embed URL from your backend and update the iframe’s src attribute. Consider implementing automatic session refresh before the TTL expires for long-running sessions.
Yes, use themes to customize the appearance of embedded reports.
Yes, inputs, filters, and other interactive features work in embedded reports.
Enable testMode: true during development to see detailed error messages. Check the browser console and network tab for additional debugging information.

​
Additional Resources