How to Create a Widget Key

Documoto Widgets allow you to embed a lightweight version of the application, parts books, or assembly pages, into an external platform, such as a dealer portal, eCommerce website, or service application.

To ensure these Widgets operate securely and only within authorized domains, each Widget must be assigned a unique Widget Key.

This article walks through everything you need to create a Widget Key, including prerequisites, the role the key plays in Widget implementation, step-by-step creation instructions, and best practices for managing Widget Keys. 

Article Topics

• Prerequisites
• Understanding the Role of a Widget Key
• How to Create a Widget Key
• Best Practices for Managing Widget Keys 

Prerequisites 

Before creating a Widget Key, the following must be in place: 

• Widgets must be enabled for the Documoto Tenant 
• A user must be assigned to User Group(s) with the "Tenant Admin" and "Widget Key Admin" permissions enabled
• A Widget User Group has been created. This group grants the Widget access to content through the group's assigned Media Categories.
  • Refer to How to Create a Widget User Group for a Widget for step-by-step instructions.
• Identify the target URL or domain (where the Widget will be hosted and embedded)

Understanding the Role of a Widget Key

A Widget Key functions as both a security credential and a configuration token. It is essential for the following: 

• Ensures the Widget can only be embedded and used on a specific hosting domain or application
• Authorizes the Widget access to content (via the assigned Organization and Widget User Group)

NOTE: Each Widget must have it's own unique Widget Key

How to Create a Widget Key 

1. Within the Documoto Admin Center, go to: System > Widgets
2. Select +Add.
3. Enter a unique, descriptive name in the Name field (e.g. Dealer Widget, eCommerce Widget, WebShop Widget)
4. Enter the domain/hostname where the Widget will be embedded in the Domain field
   • Important Note: exclude "https://" in the hosting domain
   • Valid Examples: www.documoto.com, www.oemshop.com, www.dealers.oem.com
5. Select an Organization to assign to the Widget
6. Select a User Group to assign to the Widget 
   • Note: Only groups configured as Widget User Groups will appear
7. Click Save. 

After saving: 

• Documoto will generate and display the Widget Key (also referred to as the "Authorization Token")
• You must copy and securely store the Widget Key immediately 

IMPORTANT NOTE: the Widget Key is only displayed once. After closing 
or navigating away from the screen, it cannot be viewed or retrieved 
again later

Best Practices for Managing Widget Keys 

• Store Widget Keys securely in a password manager or a restricted-access system
• Treat Widget Keys like credentials; exposing them may compromise secure access to your content.
• Revoke unused Widget Keys as needed to maintain security hygiene