API Integration Guide

Choose Your Integration Option

DS Templates supports two integration approaches. Select the one that best fits your platform.

Feature Comparison

Authentication SHARED

All /api/v1/* endpoints are protected by OAuth 2.0 using the client_credentials grant. You exchange a client_id and client_secret for an access token, then attach that token to subsequent requests as a Bearer token.

Tokens are short-lived (one hour). Refresh tokens are not issued for the client_credentials grant - when an access token expires, request a new one with the same credentials.

Token Endpoint

POST /api/v1/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=<your_client_id>&
client_secret=<your_client_secret>&
scope=<space_separated_scopes>

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "scope": "templates:read templates:write"
}

{
    "error": "invalid_client",
    "error_description": "Client authentication failed",
    "message": "Client authentication failed"
}

Available Scopes

Using a token

GET /api/v1/my-templates HTTP/1.1
Host: templates.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

For embedded routes under /embed/*, you may also pass the token as a ?token=... query parameter on the iframe URL.

Example: full token flow

# 1. Exchange credentials for an access token
ACCESS_TOKEN=$(curl -s -X POST https://templates.example.com/api/v1/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=01HRX...' \
  -d 'client_secret=s3cr3t...' \
  -d 'scope=templates:read' \
  | jq -r .access_token)

# 2. Call an API endpoint with the token
curl -s https://templates.example.com/api/v1/my-templates \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq .

Subuser Management SHARED

A subuser is the account that ultimately edits templates and owns saved work. Your integrator_user provisions one subuser per end-user in your CMS. All routes require a Bearer token with subusers:manage scope.

Create subuser

{
    "email": "alice@partner-cms.example",
    "firstName": "Alice",
    "lastName": "Andersson",
    "permissions": {
        "templateEditor": {
            "elementPositioning": true,
            "elementAnimation": true,
            "elementColor": true,
            "elementColorPicker": true,
            "fontSize": true,
            "fontType": true,
            "fontColor": false,
            "fontStyling": false
        }
    }
}

{
    "userId": "01HRX...",
    "email": "alice@partner-cms.example",
    "firstName": "Alice",
    "lastName": "Andersson",
    "clientId": "abc123...",
    "clientSecret": "xyz789...",
    "permissions": { /* ... */ },
    "created": true
}

List subusers

{
    "subusers": [
        {
            "userId": "01HRX...",
            "email": "alice@partner-cms.example",
            "firstName": "Alice",
            "clientId": "abc123...",
            "permissions": { /* ... */ }
        }
    ]
}

Get single subuser

Update subuser

{
    "firstName": "Alice",
    "lastName": "Andersson-Williams",
    "permissions": {
        "templateEditor": {
            "fontColor": true
        }
    }
}

Delete subuser

Editor Permissions

The permissions.templateEditor object controls which UI affordances are exposed inside the editor. Defaults are permissive - omit the object for full access.

Template Library SHARED

Three endpoints power the template-picker and "My Templates" views. All run on a subuser token with templates:read scope.

[
    {
        "categoryName": "Information",
        "translations": {
            "nl_NL": "Informatie",
            "en_GB": "Information",
            "de_DE": "Informationen"
        },
        "items": [
            {
                "name": "Office welcome screen",
                "slug": "info_welcome_screen",
                "isRealtime": false,
                "imagePath": "https://common.digitalsignage-templates.com/template_previews/nl/info_welcome_screen.jpg",
                "editorUrl": "https://templates.example.com/embed/template-editor/new/info_welcome_screen",
                "previewUrl": "https://templates.example.com/template/info-welcome-screen/preview"
            }
        ]
    }
]

Template Categories

[
    {
        "name": "Information",
        "translations": {
            "nl_NL": "Informatie",
            "en_GB": "Information"
        }
    }
]

Saved Templates (My Templates)

[
    {
        "id": "01HRX...",
        "name": "Reception screen - Q2",
        "aspectRatio": "16:9",
        "url": "https://templates.example.com/template/01HRX...",
        "createdAt": "2026-04-12T08:30:00+00:00",
        "modifiedAt": "2026-05-19T14:02:11+00:00",
        "thumbnailUrl": "https://...",
        "duration": 15,
        "latestVersionId": "01HSY...",
        "versions": [
            { "id": "01HRX...", "modifiedAt": "2026-04-12T08:30:00+00:00" },
            { "id": "01HSY...", "modifiedAt": "2026-05-19T14:02:11+00:00" }
        ]
    }
]

Template Versioning

DS Templates retains every saved version. The id at top level is the root (original); each save creates a new child in versions[]. latestVersionId is always the most recent.

• For rendering on screens: pass whichever version ID you want to display. Different screens can show different versions.
• For editing: always pass latestVersionId. The editor clones the version on save, keeping history linear.

Editor Iframe SHARED

The template editor is loaded in an iframe. The editorUrl from the template library response is the iframe source, with the token appended.

https://templates.example.com/embed/template-editor/new/{slug}?token={access_token}
https://templates.example.com/embed/template-editor/edit/{id}?token={access_token}

<iframe
    id="template-editor"
    src="https://templates.example.com/embed/template-editor/new/info_welcome_screen?token=eyJ..."
    style="width:100%;height:100vh;border:none"
    sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
></iframe>

Module Iframes SHARED

Each module exposes its own configuration UI as an iframe. Unlike the editor, module iframes do not use postMessage - they are server-rendered pages that the user interacts with directly.

https://templates.example.com/embed/modules/{link}?token=<subuser-token>

<iframe
    src="https://templates.example.com/embed/modules/birthday-module/?token=eyJ..."
    sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
></iframe>

Module categories

PostMessage Reference

Every window.postMessage event exchanged between your parent CMS and the platform's iframes.

Editor Protocol

Events for the editor iframe at /embed/template-editor/...

Editor to Parent

Parent to Editor

Event listener example

const ORIGIN = 'https://templates.example.com';
const editor = document.getElementById('template-editor');

window.addEventListener('message', (event) => {
    if (event.origin !== ORIGIN) return;

    switch (event.data.type || event.data.msg) {
        case 'DST_EDITOR_READY':
            console.log('Editor ready');
            break;

        case 'DST_SAVE_COMPLETE':
            console.log('Saved:', event.data.templateId);
            refreshUserTemplates();
            break;

        case 'DST_SAVE_ERROR':
            console.error('Save failed:', event.data.error);
            break;
    }
});

// Trigger save from your CMS UI
function triggerSave() {
    editor.contentWindow.postMessage(
        { type: 'DST_EDITOR_SAVE' }, ORIGIN
    );
}

Playback Protocol

For templates in playback mode via /template/{slug}/preview?playlist=true. Without ?playlist=true the template auto-plays standalone.

Template to Parent

Parent to Template (raw strings)

Minimum playback flow

parent: load <iframe src="/template/{slug}/preview?playlist=true" />
iframe -> parent: { msg: "DST_TEMPLATE_LAZY_LOAD" }
iframe -> parent: { msg: "preRenderFinished" }
iframe -> parent: { msg: "DST_TEMPLATE_DURATION", duration: 30 }
parent -> iframe: "initIntroAnimation"
iframe -> parent: { msg: "DST_TEMPLATE_PLAY", startTime: 173... }
... template plays ...
parent -> iframe: "exitIntroAnimation"
iframe -> parent: { msg: "DST_TEMPLATE_STOP", playDuration: 30000 }

iframe -> parent: { type: "DST_RENDERER_MEDIA_URL_REQUEST",
                   fileNameWithExtension: "office.jpg" }
parent -> iframe: { type: "DST_RENDERER_MEDIA_URL_RESPONSE",
                   fileNameWithExtension: "office.jpg",
                   mediaUrl: "https://your-cdn.example/uploads/office.jpg" }
iframe: updates all img.src, video.src, and inline-style references

Error Handling SHARED

Every JSON endpoint uses the same error shape: { "error": "Human-readable description" }. The HTTP status carries the semantics.

Common error messages

These are the canonical error strings the API returns. Treat the HTTP status as the source of truth.

Authentication and authorisation

Provisioning (POST /users/provision)

Subuser management

Library and branding

Template editor save

The editor save endpoint wraps errors in a success envelope:

{
    "success": false,
    "error": "Validation failed",
    "errors": [
        "The first headline must not be empty.",
        "Brand color 1 must be a valid hex code."
    ]
}

Note: the wrapping HTTP status may be 200 - check the success field, not the status. The editor's DST_SAVE_ERROR postMessage passes through the errors array verbatim. A 401 inside the iframe means the token expired and returns server-rendered HTML instead of JSON.

Rendering (GET /template/{id})

Validation error shapes

Two slightly different shapes depending on context:

JSON-API endpoints (/api/v1/...) - a single error string:

{ "error": "email is required" }

Editor-iframe save (/embed/template-editor/...) - JSON wrapped in success envelope (see above).

What to retry vs. surface

Rendering Templates SHARED

Once a subuser has saved a template, embed it on a digital signage screen by loading the rendering URL in an iframe.

Required: integrator host

Saved templates may only be rendered from a host the platform recognises as one of your integrator domains. A request from any other host returns 400: "API templates must be served from a recognized integrator domain."

Required: trackingId

Every render request must carry a ?trackingId= query parameter - a stable identifier for the device displaying the template (e.g. screen serial number, device UUID). Used for usage counting and deduplication.

• One trackingId per screen, not per render - reusing is correct and expected
• Do not generate a fresh ID per render - that inflates counters
• Do not derive from end-user PII

Recommended: ?playlist=true

Without ?playlist=true, the template auto-plays with no external control. With it, the template enters parent-driven mode: pre-renders, emits preRenderFinished, then waits for 'initIntroAnimation'. See the Playback Protocol section above.