Skip to content

API Credentials

If your plugin needs to fetch data from the Livespace API, it can request temporary session credentials via postMessage. This is optional — plugins that only display the context data from the context message do not need it.

Requesting credentials

Send this message from the iframe to the host:

{
  "type": "livespace-plugin:request-api-credentials",
  "payload": { "requestId": "<uuid-generated-per-request>" }
}
  • Generate requestId with crypto.randomUUID().
  • Track pending requests in a Map keyed by requestId so you can correlate replies.
  • Set a per-request timeout (10–15 s) that rejects the Promise if no reply arrives — otherwise a dropped host leaves the plugin hung.

Receiving credentials

The host replies with:

{
  "type": "livespace-plugin:api-credentials",
  "payload": {
    "requestId": "<echoed-from-request>",
    "apiBaseUrl": "https://your-account.livespace.io",
    "apiKey": "...",
    "apiSha": "...",
    "apiSession": "..."
  }
}

Important

  • Always correlate replies via requestId. Drop any reply whose requestId does not match a pending request — never accept unsolicited credentials.
  • Each apiSession is one-shot — it is consumed by exactly one API call. Two parallel calls require two separate credential requests with distinct requestId values.
  • Sessions expire after 15 minutes. Request credentials at the moment of the call, not at plugin startup.