> ## Documentation Index
> Fetch the complete documentation index at: https://docs.papermap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

This guide covers security, performance, scalability, and troubleshooting best practices for production multi-tenant applications.

### Performance Optimization

1. **Cache tenant configurations**: Reduce API calls by caching tenant settings
2. **Use CDN for embeds**: Serve embedded dashboards through a CDN
3. **Implement lazy loading**: Load dashboards only when needed
4. **Monitor performance per tenant**: Track load times and API response times

### Security Best Practices

1. **Never expose API keys**: Always generate tokens server-side
2. **Implement CORS**: Restrict embed domains per tenant
3. **Use HTTPS everywhere**: Enforce secure connections
4. **Audit trail**: Log all tenant access and modifications
5. **Regular security audits**: Review tenant access patterns

### Scalability Considerations

1. **Database per tenant**: For large clients, consider dedicated databases
2. **Implement rate limiting**: Prevent resource exhaustion
3. **Queue background jobs**: Process tenant tasks asynchronously
4. **Monitor resource usage**: Alert on unusual patterns
5. **Plan for growth**: Design for 10x current tenant count

## Troubleshooting

### Common Issues

**1. Tenant data mixing**

* Verify workspace IDs are correct
* Check API key scoping
* Review query filters

**2. Branding not applying**

* Clear browser cache
* Verify branding configuration
* Check embed parameter syntax

**3. Performance degradation**

* Review tenant resource usage
* Implement query optimization
* Consider tenant database sharding

**4. Authentication failures**

* Verify API keys are active
* Check token expiration
* Review CORS configuration

### Debugging Multi-Tenant Issues

Enable debug mode in embeds:

```html theme={null}
<iframe
  src="https://papermap.ai/embedded/dashboard?embedded-token=YOUR_TOKEN&debug=true"
></iframe>
```

Check browser console for detailed error messages and network requests.

## Migration Guide

### Moving from Single to Multi-Tenant

If you're migrating from a single-tenant to multi-tenant architecture:

1. **Audit current setup**: Document existing data sources and dashboards
2. **Plan tenant structure**: Decide how to split existing data
3. **Create tenant workspaces**: Set up workspaces for each tenant
4. **Migrate data**: Export and import data to appropriate tenants
5. **Update embed codes**: Replace single workspace with tenant-specific embeds
6. **Test thoroughly**: Verify data isolation and permissions
7. **Deploy gradually**: Roll out to tenants in phases

## Next Steps

* Read the [Embedding Guide](/documentation/embedding) for more on embedding
* Join our [Community Forum](https://discord.gg/BbjGm8jW) for discussions
* Contact [team@papermap.ai](mailto:team@papermap.ai) for enterprise guidance

***

*Ready to build a multi-tenant analytics platform? [Book a session](https://calendly.com/admin-pappermap/30min) and we will help you enable multi-tenancy.*