Skip to main content
This guide provides an overview of implementing secure tenant dashboard management using HMAC signature authentication for enterprise-grade multi-tenant security.

​
Architecture Overview

Your API (Tenant Management)
    ↓
HMAC Signed Request → Papermap Dashboard API
    ↓
Dashboard Created/Retrieved
    ↓
Generate Iframe Token (HMAC Signed)
    ↓
Frontend Embeds Dashboard

​
Key Components

  1. TenantDashboard Model - Maps tenants to Papermap dashboards
  2. HMAC Signature Service - Securely authenticates API requests
  3. Dashboard Handler - Creates dashboards and generates embed tokens
  4. Dashboard Router - API endpoints for dashboard operations

​
Quick Start

Follow these guides in order to implement the backend:
1

Set Up Authentication

Implement HMAC signature authentication to securely communicate with the Papermap API.

HMAC Authentication

Learn how to implement HMAC-SHA256 signature authentication
2

Create Dashboards

Set up the ability to create and manage dashboards for your tenants.

Creating Dashboards

Learn how to create dashboards via the Papermap API
3

Generate Embed Tokens

Generate secure tokens to embed dashboards in your frontend.

Iframe Embed Tokens

Learn how to generate secure embed tokens
4

Build API Endpoints

Create REST API endpoints for your frontend to interact with.

API Endpoints

Example REST API endpoints for dashboard operations
5

Secure Your Implementation

Follow security best practices for production deployment.

Security Best Practices

Learn about security considerations and best practices

​
Database Model

First, create a model to link your tenants to their Papermap dashboards:
It is not required to save it this way, but you need to have a way to map your tenant to their dashboards.
from sqlalchemy import  Column, String

from .database import Base
class TenantDashboard(BaseModel):
    __tablename__ = 'tenant_dashboards'

    tenant_id = Column(String(255), nullable=False, index=True)
    workspace_id = Column(String(255), nullable=False)
    dashboard_id = Column(String(255), nullable=False)
Purpose: Links your tenant to a Papermap dashboard ID for secure access and isolation.

​
Prerequisites

Before implementing, ensure you have:
  • Papermap API credentials (API Key ID and Secret Key)
  • Your workspace ID
  • API endpoint URL (obtain from your Papermap dashboard settings)
Security Best Practices: - Never hardcode API endpoints, keys, or secrets in your code - Always use environment variables or a secrets management system
  • The API endpoint URL should be treated as sensitive configuration - Store credentials securely and rotate them regularly

​
Environment Configuration

Store your credentials securely in environment variables:
.env
PAPERMAP_API_KEY_ID=your-api-key-id
PAPERMAP_SECRET_KEY=your-secret-key-never-share
PAPERMAP_API_URL=<your-api-endpoint>
Obtaining Your Configuration: - API Credentials: Available in your Papermap dashboard under Settings → API Keys - API Endpoint: Available in Settings → API Configuration - Always use the values provided in your dashboard for your specific workspace

​
Implementation Guides

HMAC Authentication

Implement secure HMAC signature authentication

Creating Dashboards

Create and manage dashboards for tenants

Iframe Tokens

Generate secure embed tokens

API Endpoints

Build REST API endpoints

Tenant Usage

Track per-tenant credit consumption

Security

Security best practices

Best Practices

Performance and scalability tips

​
Common Pattern Reference

The HMAC signature pattern for tenant dashboards follows this flow: 
1. Create Payload
   payload = workspace_id + valid_until

2. Generate Signature
   signature = HMAC-SHA256(payload, secret_key)

3. Send Request with Headers
   X-API-Key-ID: <api_key>
   X-Workspace-ID: <workspace_id>
   X-Valid-Until: <timestamp>
   X-Signature: <signature>

4. Store Result
   tenant_id → dashboard_id mapping

5. Generate Embed Token
   Encode {tenant_id, dashboard_id, signature, expires} as base64
This pattern ensures secure, time-limited access to tenant-specific dashboards.

​
Next Steps

Frontend Setup

Learn how to embed dashboards in your frontend application