Tutorial: Token-based embeds

Lucid's Embed API enables you to display a Lucid document directly in your web page using an <iframe>, so users can view or edit the document directly without leaving your page.

Token-based embeds can be viewed by any user, even without a Lucid account, but are more complicated to use than cookie-based embeds. For a more detailed comparison, see the Lucid Embed APIs overview.

This page will walk you through creating a token-based embed application.

Step 1: Create an application

1. Go to the developer portal.
2. Create a new application.
3. Create an OAuth2 client for your application.
4. Grab your client ID and client secret. You’ll need it in the next step!

Step 2: Obtain an access token

Use Lucid's OAuth2 flow to obtain an access token for a user who wants to create token-based embeds. You will need to use that user's access token anytime their embed is viewed (regardless of the user who's viewing the embed). This means you should request the offline_access scope to obtain a refresh token, which you'll then use to get new access tokens as needed.

You also should request a scope that gives you permission to create embeds, such as lucidchart.document.app.picker. (For a comprehensive list of scope options, check the documentation for the generate embed session token endpoint , which we'll use in the next step.)

Step 3: Create an embed session token

Each time a user wants to create or view an embed in your app, call the "generate embed session token" API endpoint to obtain an embed session token. (Note: each embed session token is short-lived and must only be used by a single user. You should generate a new one each time any user wants to view or create an embed.)

To allow the user to create a new embed, make a request with no embed ID in the request body (more about embed IDs later). The origin field should be the origin of the page that will contain the iframe.

POST https://api.lucid.co/embeds/token

{
  "origin": "https://yourapp.example"
}

Call the "generate embed session token" API endpoint to obtain an embed session token. Because the embed session token is short-lived, you should generate a new one each time an embed is accessed in your app. To view an existing embed, the embed ID should be included in the request body. To just load the document picker component and create a new embed, an embed ID is not needed.

With the resulting embed session token, display an iframe to the user with this URL: https://lucid.app/embeds?token=<embed session token>. The user will be shown a "document picker", where they can select a Lucid document to embed and choose the embed settings.

❓

Aside: what embed settings are available?

When creating an embed, users can configure the following settings:

• Access level: can other users edit the document in this embed, only comment, or only view it?
• For view-only embeds: what viewer type should be used (a rich interactive viewer, or a lightweight image-based viewer)?
• For view-only embeds: should the embed automatically update when changes are made in Lucid? (defaults to true)
• Custom settings for your app, if applicable (more on this in Step 5 below)

After the user creates an embed, the iframe will emit an EmbedCreated event in a message to the parent window.

{
  "type": "LucidEmbedEvent",
  "event": "EmbedCreated",
  "documentId": "dba2b0b8-959c-44c9-bc42-73d4d1b3f157",
  "embedId": "6867b573-b774-4a63-9552-c03d98a5420c",
  "signature": "..."
}

The embedId in the event is what you should store in your app. You'll use it later when displaying the embed to other users. (See this documentation for more about the structure of the embed event.)

Step 4: Create an embed session token (to view an existing embed)

To view an existing embed, call the "generate embed session token" endpoint again, and include the embed ID you obtained when the user created the embed. Use the access token of the user who created the embed. (You don't need an access token for the user viewing the embed.)

POST https://api.lucid.co/embeds/token

{  
  "origin": "https://yourapp.example",  
  "embedId": "6867b573-b774-4a63-9552-c03d98a5420c"  
}

Same as above, display an iframe to the user with this URL: https://lucid.app/embeds?token=<embed session token>.

Step 5 (optional): add custom settings to the UI

To customize the behavior of the embed iframe, you can use the optional sessionConfig field when requesting a session token.

For example, if you have custom settings you want to expose for each embed (such as embed size settings), you can include "customSettings": "postMessage" to display a "settings for this app" button in the embed settings UI:

POST https://api.lucid.co/embeds/token

{  
  "origin": "https://yourapp.example",  
  "sessionConfig": {  
    "customSettings": "postMessage"  
  }  
}

When a user clicks on the button in the embed iframe, the iframe emits an OpenCustomSettings event:

{  
  "type": "LucidEmbedEvent",  
  "event": "OpenCustomSettings"  
}

Your app can then display whatever additional settings UI is desired. Note: it's entirely up to your app to implement the custom settings UI, including storing those settings alongside the embed's embed ID.