codatum.comSign InStart for free

How to Set Up Signed Embed

Seamlessly Integrate notebook into external services.

How to Set Up

Prepare integration

  • Prepare API Key and Secret

    • Open Workspace settings and click menu API Keys.

    • Click the Add API Key button and create new API Key.

    • Make a note of the API Key and API Secret (they will be used later for API calls).

  • Open the notebook

    • Open the notebook you want to share.

    • Click the Share button in the header and select Signed Embed tab.

  • Select Pages

    • Choose the pages you want to publish.

  • Publish

    • Click the Publish button.

  • Configure integration settings.

    • Add API Key to use in Permitted API Keys section.

    • If you want to overwrite parameter values via the API, configure them in the Externalized Params section

Issue token from server

  • The following API is used to issue a token

    • The required arguments for calling the API can be found on the Setup guide tab.

    • Perform the API call on the server side to prevent the API Secret from being exposed externally.

    • Issue a token for each user session, and do not reuse it (it expires after 1 hour).

post
Body
api_keystring · min: 24 · max: 24Required

API Key. Can be issued from 'Workspace settings > API Keys'

Example: 6729a28bc7100424ad4e2e5d
api_secretstring · min: 32 · max: 32Required

API Secret. Generated when issuing 'API Key'

Example: c711defdff5f4e3e8e53d4f408579b9a
integration_idstring · min: 24 · max: 24Required

Integration ID. Can be obtained from the signed embed settings

Example: 671ef14b0d08cf6c657df7da
page_idstring · min: 24 · max: 24Required

Page ID to be displayed in the notebook. Can be obtained from the signed embed settings

Example: 671ecbbf2990c63fea3b3a26
token_user_idstring · min: 1Required

Specify the user ID within the application where the notebook is embedded. Ensure that the token can uniquely identify the token user for security reason.

expires_ininteger · min: 1 · max: 86400Optional

Token expiration time in seconds. Default is 3600 seconds (1 hour)

Example: 3600
cache_max_ageinteger · max: 86400Optional

Cache max age in seconds. Default is 86400 (24 hours)

Example: 86400
Responses
200
Generated token
application/json
post
POST /api/notebook/issueToken HTTP/1.1
Host: api.codatum.com
Content-Type: application/json
Accept: */*
Content-Length: 313

{
  "api_key": "6729a28bc7100424ad4e2e5d",
  "api_secret": "c711defdff5f4e3e8e53d4f408579b9a",
  "integration_id": "671ef14b0d08cf6c657df7da",
  "page_id": "671ecbbf2990c63fea3b3a26",
  "token_user_id": "text",
  "params": [
    {
      "param_id": "6722c7061b02448a4056d84d",
      "param_value": "\"Hello world\""
    }
  ],
  "expires_in": 3600,
  "cache_max_age": 86400
}
{
  "token": "(Generated-token)"
}

Embed iframe

Embed HTML into your service using the Signed Embed URL. You can set display options along with the token. Please check the Setup guide in for details.

[Recommended] Pattern1. Passing token via postMessage

  1. Create an iframe element with Signed Embed URL as the src attribute

  2. Wait for a {type: "READY_FOR_TOKEN"} message from the iframe via postMessage

  3. Send {type: "SET_TOKEN", token: "{{ TOKEN_HERE }}"} message back to the iframe via postMessage (Optionally, you can also send displayOptions)

// Sample

const NOTEBOOK_ORIGIN = 'https://app.codatum.com';
const ingegrationUrl = 'https://app.codatum.com/protected/workspace/xxx/notebook/xxx?theme=LIGHT&locale=en-US';
const token = '{{ TOKEN_HERE }}';  // Issued token here
const displayOptions = {
  "sqlDisplay": "SHOW",
  "expandParamsFormByDefault": false
};

// Store iframe window reference
let notebookWindow: Window | null = null;

// Create and insert iframe
function createDashboard(containerId: string) {
  const container = document.getElementById(containerId);
  if (!container) return;

  const iframe = document.createElement('iframe');
  iframe.src = ingegrationUrl;
  iframe.allow = 'fullscreen;clipboard-write';
  container.appendChild(iframe);
  notebookWindow = iframe.contentWindow;
}

// Handle messages from iframe
function handleMessage(event: MessageEvent<{type: 'READY_FOR_TOKEN'}>): void {
  // Verify origin and source
  if (event.origin !== NOTEBOOK_ORIGIN || event.source !== notebookWindow) {
    return;
  }

  // Send token when iframe is ready
  if (event.data.type === 'READY_FOR_TOKEN') {
    const message = {
      type: 'SET_TOKEN',
      token: token,
      displayOptions: displayOptions
    };    
    notebookWindow?.postMessage(message, NOTEBOOK_ORIGIN);
  }
}

function cleanup() {
  window.removeEventListener('message', handleMessage);
  notebookWindow = null;
}

export function createEmbeddedNotebook(containerId: string) {
  window.addEventListener('message', handleMessage);
  createDashboard(containerId);
  return cleanup;
}

Pattern2. Passing token via URL parameter

  1. Append token as a query parameter to the Signed Embed URL (?token=xxx)

  2. Optionally, append displayOptions as a query parameter (The value should be encodeURIComponent(JSON.stringify(displayOptions)))

  3. Create an iframe element with the modified URL as the src attribute

// Sample

<iframe
  src="https://app.codatum.com/protected/workspace/xxx/notebook/xxx?theme=LIGHT&token={{ TOKEN_HERE }}&displayOptions={{ ENCODED_DISPLAY_OPTIONS_HERE }}"
  allow="fullscreen; clipboard-write" 
/>

Appendix: Message list

Messages can be exchanged using the iframe's postMessage function.

  • The messages are also output to console.debug(), so you can check the actual message content there.

  • For example, this functionality can be used to:

    • Persist parameter information modified by users.

    • Share parameters across different integrations or pages.

Below is a list of messages that can be sent and received.

Messages to the iframe

type
description

SET_TOKEN

Set the authentication token and start rendering notebook. This message must be sent after receiving the READY_FOR_TOKEN message.

This message can be sent multiple times to the same iframe, which will cause the iframe to reload internally with the new token and parameters.

The parameters field allows you to set initial values for parameters that are not fixed or defaulted on the server side. This is useful when you want to provide parameter input fields in your application.

{
  type: "SET_TOKEN",
  token: "...",
  displayOptions: {
    "sqlDisplay": "SHOW",
    "expandParamsFormByDefault": false
  },
  parameters: [
    {
      param_id: "662a5e9fce6482ca0231f06f",
      param_value: "\"Hello codatum\""
    }
  ]
}

Messages from the iframe

type
description

READY_FOR_TOKEN

Notification that the notebook is ready to receive the token.

{type: "READY_FOR_TOKEN"}

PARAM_CHANGED

Sent each time the user modifies a parameter within the notebook.

{
  type: "PARAM_CHANGED",
    params: [
        {
            param_id: "662a5e9fce6482ca0231f06f",
            param_value: "\"Hello codatum\""
        },
    ]
}

EXECUTE_SQLS_TRIGGERED

Sent when 'Run all' is executed within the notebook.

{
    type: "EXECUTE_SQLS_TRIGGERED",
    params: [
        {
            param_id: "662a5e9fce6482ca0231f0aa",
            param_value: "123"
        }
    ]
}
PreviousSigned EmbedNextParameter Specifications

Last updated

Was this helpful?