How to Set Up Signed Embed

Seamlessly Integrate notebook into external services.

How to Set Up

Prepare signed embed

• 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.

• Publish signed embed

  • Choose the pages you want to publish.

  • Set the options for publishing.

  • Click the Publish button.

• Configure signed embed settings.

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

  • If you want to set parameter values when issuing a token, configure them in the Server-side parameters section.

Issue token from server

• Use the following API 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 by default).

post

Body

application/json

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

tokenstringRequiredExample: (Generated-token)

400

Bad request

application/json

401

Unauthorized

application/json

post

/api/notebook/issueToken

HTTPcURLJavaScriptPython

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 in frontend

• Use Codatum Embed SDK to embed in your frontend

  • The embedUrl required for embedding can be found on the Setup guide tab

  • Set tokenProvider to the API that issues tokens on the server side

  • For all other configurable options, see the SDK README

Appendix

Frequently Asked Questions

Getting "Missing param: xxx" error when issuing a token

• To issue a token, all server-side parameters must be included in the request

• This error occurs when a parameter with the ID "xxx" is not included in the request

Getting "The following parameters must be set by the server" error when sending client-side parameters

• You are trying to change server-side parameters when sending client-side parameters

• To change server-side parameters, a new token must be issued

Parameters not updating when sending client-side parameters

• Check that the parameter you are sending is not specified as a server-side parameter

• Verify that param_value is in the correct JSON string format

• Confirm that param_id matches an existing parameter ID