Integration steps

The steps for integrating a signed embed into an external app. For a feature overview, see Signed embed.

Prepare

1. Open global nav > Workspace settings > API keys, then create an API key. Keep the API key and API secret on hand.
2. Publish from Share > Signed embed on the notebook screen.
3. On the settings screen, add the API key you'll use to API keys granted permission.
4. If you need data isolation per tenant, or need to restrict the embedding domain, configure Server-side parameters or Allowed origins.

You can check a sample token-issuance request and the embed URL from Setup guide on the settings screen.

Issuing a token

Call the following API server-side. Handle the API secret server-side only, and don't include it in the frontend. For the same user (token_user_id), the same fixed values, and the same audit_note, you can reuse the token within its expiration period. Reissue it when any of them changes.

See Token issuance API for the OpenAPI spec. The JSON URL is as follows.

https://api.codatum.com/api/notebook/spec.json

Request

Field	Required	Description
api_key	Required	The API key.
api_secret	Required	The API secret.
integration_id	Required	The signed embed's ID. You can check this on the settings screen.
page_id	Required	The ID of the page to display. You can check this on the settings screen.
token_user_id	Required	An ID that uniquely identifies the user within the embedding app. Used for auditing and for access control of run results. Doesn't affect Codatum workspace permissions.
params	Required	An array of server-side parameters. Each element has param_id and param_value (a JSON-stringified value). You must include every server-side parameter you've configured. Even if you don't use server-side parameters, send an empty array [].
expires_in	Optional	The token's expiration, in seconds. Defaults to 3600; the maximum is 86400.
cache_max_age	Optional	The maximum cache duration, in seconds. Defaults to 86400; the maximum is 86400. 0 disables caching.
audit_note	Optional	An arbitrary string recorded in the audit log for operations performed with this token. Codatum doesn't interpret it, and it doesn't affect behavior. The token carries it, so don't include confidential information. Up to 256 characters (Limits and constraints).

Response

Field	Description
token	The issued token.

Embedding on the frontend

Use the Codatum Embed SDK to embed on the frontend. The packages are as follows.

• @codatum/embed: the core SDK
• @codatum/embed-react: a wrapper for React
• @codatum/embed-vue: a wrapper for Vue

You can check the embed URL (embedUrl) from Setup guide on the settings screen. See each package's README for installation, options, and events.

import { createEmbed } from '@codatum/embed';

const embed = createEmbed({
  container: '#dashboard',
  embedUrl: 'https://app.codatum.com/protected/workspace/<wsId>/notebook/<integrationId>',
  tokenProvider: async () => {
    const res = await fetch('/api/codatum/token', { method: 'POST' });
    const data = await res.json();
    return { token: data.token };
  },
});
await embed.init();

tokenProvider is a callback where your own server issues and returns a token. It's called on initialization, on reload, and when the token is refreshed before it expires.

See the FAQ for common questions about integration.