1. Version

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='version'></req>
</wink_api>

<wink_api>
    <resp id="1" command="version" status="ok">1.4</resp>
</wink_api>

2. Input Control - Start, Stop, Restart

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='restart'>WF05-2657-1C04-7F1B-5EC0</req>
</wink_api>

<wink_api>
    <resp id="1" command="restart" status="ok">WF05-2657-1C04-7F1B-5EC0</resp>
</wink_api>

3. IP Based Input Control

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='stopip'>10.130.90.68:554</req>
</wink_api>

<wink_api>
    <resp id="1" command="stopip" status="ok">WF05-2657-1C04-7F1B-5EC0</resp>
</wink_api>

4. Get GUID

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='getguid'>10.130.90.199:8382</req>
</wink_api>

<wink_api>
    <resp id="1" command="getguid" status="ok">WF05-2657-1C04-7F1B-5EC0</resp>
</wink_api>

5. GUID Status

6. Block GUID

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='blockguid'>WF05-2657-1C04-7F1B-5EC0</req>
</wink_api>

7. Unblock GUID

8. Block IP

9. Unblock IP

10. Input Stream Properties

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='input_source'>
        <input title='Test Camera' 
               desc='Testing stream' 
               type='RTSP' 
               path='rtsp://192.168.1.100:554/stream1'
               fps='30'
               width='1920'
               height='1080'
               enabled='1' />
    </req>
</wink_api>

11. Input Stream Delete

12. Create User

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='createuser'>
        <name>Billy Armstrong</name>
        <username>billy</username>
        <password>SecurePass123!</password>
        <access>2</access>
    </req>
</wink_api>

13. Delete User

14. Change Password

15. Event Logger

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='log'>API integration test successful</req>
</wink_api>

16. Flush Logs

17. Reboot Server

1. Version

Same as WINK Forge version command - returns API version number.

2. Archive Control

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='archiver_start'>WMA5-6E0F-1C04-86F2-E5C4</req>
</wink_api>

3. Archiver Status

<wink_api>
    <resp id="11" command="archiver_status" status="ok">
        <archiver guid="WMA5-6E0F-1C04-86F2-E5C4" 
                  title="TV2" 
                  desc="Conference Room Feed" 
                  type="RTMP" 
                  path="rtmp://10.130.90.10/public/stream_high" 
                  segmenttime="5" 
                  meta1="Building A" 
                  meta2="Floor 2" 
                  meta3="Room 201" 
                  meta4="PTZ Camera" 
                  enabled="1" />
    </resp>
</wink_api>

4. Archiver Source

5. Archive Delete

1. Create OTP Token

curl -d "apiuser=apiuser&apipass=apipass&action=create&duration=300" \
     -X POST http://router.example.com/otp/api/

2. Extend / Remove OTP

curl -d "apiuser=apiuser&apipass=apipass&action=extend&token=836352163502&duration=300" \
     -X POST http://router.example.com/otp/api/

curl -d "apiuser=apiuser&apipass=apipass&action=remove&token=836352163502" \
     -X POST http://router.example.com/otp/api/

3. Version

curl -d "apiuser=apiuser&apipass=apipass&action=version" \
     -X POST http://router.example.com/otp/api/

OTP Integration FAQ

The questions below come up regularly during web portal and partner integrations.

http://router.example.com/200/public/hls/<stream>.m3u8?otp=836352163502

Integrator Security Checklist

Confirm every item below before an OTP integration goes live in front of the public. If any answer is "no," the integration is exploitable in the way described in Anti-patterns.

OTP Code Examples

The cURL calls above show the raw requests. The examples below show the same calls in context, issuing and maintaining one token per viewer session. In every example the credentials stay on the server and only a finished, short-lived URL reaches the browser — copy that shape, not just the API calls.

PHP: Per-Session Token

Creates a token on the visitor's first request, reuses it for the rest of the session, and extends it when it is close to lapsing:

<?php
session_start();

// Mint only for a caller you have already authenticated. Without this check the page
// is a public minting endpoint - the anti-pattern in "Real cases" above.
if (empty($_SESSION['user_id'])) {
    http_response_code(401);
    exit('Not authenticated');
}

// One endpoint for every action. The trailing slash is required.
$otp_api  = 'https://router.example.com/otp/api/';
$api_user = 'apiuser';
$api_pass = 'apipass';
$playlist = 'https://router.example.com/200/public/hls/WF05-333F-4D5C-E636-2937.m3u8';

// Token lifetime in SECONDS - 1 to 900, default 600 if omitted.
$duration = 300;

// Renew at a third of the lifetime, so a slow request cannot land past expiry.
// There is no query action, so the clock is entirely ours to keep.
$refresh_at = (int) ($duration / 3);

function otp_post($url, $fields) {
    $options = array(
        'http' => array(
            'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
            'method'  => 'POST',
            'content' => http_build_query($fields),
            'timeout' => 10,
            ),
        );

    $result = @file_get_contents($url, false, stream_context_create($options));
    return ($result === false) ? '' : trim($result);
}

// Still watching and the token is getting on - extend rather than issue a second one.
if (!empty($_SESSION['otp_token']) && (time() - $_SESSION['otp_minted']) > $refresh_at) {

    $resp = otp_post($otp_api, array(
        'apiuser'  => $api_user,
        'apipass'  => $api_pass,
        'action'   => 'extend',
        'token'    => $_SESSION['otp_token'],
        'duration' => $duration
        ));

    // extend answers "<token>:Token Extended"
    if (strpos($resp, ':Token Extended') !== false) {
        $_SESSION['otp_minted'] = time();
    } else {
        unset($_SESSION['otp_token']);   // extend failed - fall through and create
    }
}

// No token yet (or the extend failed) - create one for this session
if (empty($_SESSION['otp_token'])) {

    $token = otp_post($otp_api, array(
        'apiuser'  => $api_user,
        'apipass'  => $api_pass,
        'action'   => 'create',
        'duration' => $duration
        ));

    // Errors are plain text on a 200: "0:Invalid Login", "0:No Valid Command Received"
    if ($token === '' || substr($token, 0, 2) === '0:') {
        die('OTP API error: ' . htmlspecialchars($token));
    }

    $_SESSION['otp_token']  = $token;
    $_SESSION['otp_minted'] = time();
}

// Only the .m3u8 carries the token - segment requests inherit the session
$video_url = $playlist . '?otp=' . urlencode($_SESSION['otp_token']);

// Call this when the user logs out or closes the session:
// otp_post($otp_api, array('apiuser' => $api_user, 'apipass' => $api_pass,
//                          'action' => 'remove', 'token' => $_SESSION['otp_token']));
//
// Serving what the JavaScript example needs:
// header('Content-Type: application/json');
// echo json_encode(array('token'   => $_SESSION['otp_token'],
//                        'refresh' => $_SESSION['otp_minted'] + $refresh_at));
?>

JavaScript: Player Integration

The page asks its own backend for the session's token, builds the playlist URL, and requests a fresh token shortly before the current one lapses:

// hls.js instance, created once by your player setup. Declared here so the example
// is complete; swap in whatever player you use.
let hls = null;
let session = null;   // { token: "a1b2c3d4e5f6", expires: 1691234567 }
let refreshTimer = null;

async function getSessionToken() {
    const res = await fetch('/otp-token.php', { credentials: 'same-origin' });
    if (!res.ok) {
        throw new Error('Token request failed: ' + res.status);
    }
    return res.json();
}

function playlistUrl(playlist) {
    return playlist
        + '?otp=' + encodeURIComponent(session.token)
        + '&expires=' + session.expires;
}

function loadIntoPlayer(playlist) {
    const video = document.getElementById('player');
    const url = playlistUrl(playlist);

    if (video.canPlayType('application/vnd.apple.mpegurl')) {
        video.src = url;           // Safari and other native HLS players
    } else {
        hls.loadSource(url);       // hls.js or the player of your choice
    }
}

async function startStream(playlist) {
    session = await getSessionToken();
    loadIntoPlayer(playlist);
    scheduleRefresh(playlist);
}

// Refresh before expiry rather than letting playback fail. This is cleaner than
// redirecting mid-stream with expiry_url; keep expiry_message set as a fallback.
// Renew with headroom - do not re-mint on a tight timer (see "Real cases").
function scheduleRefresh(playlist) {
    const msRemaining = (session.expires * 1000) - Date.now() - 60000;   // 60s headroom

    clearTimeout(refreshTimer);
    refreshTimer = setTimeout(async function () {
        try {
            session = await getSessionToken();   // backend extends, or creates a new token
            loadIntoPlayer(playlist);
            scheduleRefresh(playlist);
        } catch (err) {
            // Do not let the chain die silently - back off and try again.
            console.error('Token refresh failed, retrying:', err);
            refreshTimer = setTimeout(function () { scheduleRefresh(playlist); }, 10000);
        }
    }, Math.max(msRemaining, 5000));
}

startStream('https://router.example.com/200/public/hls/WF05-333F-4D5C-E636-2937.m3u8')
    .catch(function (err) { console.error('Could not start stream:', err); });

C#: OTP Client

A small client wrapping the three actions, suitable for an ASP.NET application holding one token per user session:

using System;
using System.Collections.Generic;
using System.Globalization;
using System.Net.Http;
using System.Threading.Tasks;

public class WinkOtpClient
{
    private static readonly HttpClient Http = new HttpClient();

    private readonly string _apiUrl;      // https://router.example.com/otp/api/  (trailing slash required)
    private readonly string _user;
    private readonly string _pass;

    public WinkOtpClient(string apiUrl, string user, string pass)
    {
        _apiUrl = apiUrl;
        _user = user;
        _pass = pass;
    }

    private async Task<string> PostAsync(string url, Dictionary<string, string> fields)
    {
        fields["apiuser"] = _user;
        fields["apipass"] = _pass;

        using (var content = new FormUrlEncodedContent(fields))
        {
            var response = await Http.PostAsync(url, content);
            response.EnsureSuccessStatusCode();
            return (await response.Content.ReadAsStringAsync()).Trim();
        }
    }

    // Returns the raw token string. Errors arrive as "0:Invalid Login".
    // There is no query action, so record the mint time and track the lifetime yourself.
    public async Task<string> CreateAsync(int durationSeconds = 300)
    {
        var token = await PostAsync(_apiUrl, new Dictionary<string, string>
        {
            { "action", "create" },
            { "duration", durationSeconds.ToString() }   // SECONDS, 1-900 (default 600)
        });

        if (token.StartsWith("0:"))
        {
            throw new InvalidOperationException("OTP API error: " + token);
        }

        return token;
    }

    public async Task<bool> ExtendAsync(string token, int durationSeconds = 300)
    {
        var result = await PostAsync(_apiUrl, new Dictionary<string, string>
        {
            { "action", "extend" },
            { "token", token },
            { "duration", durationSeconds.ToString() }
        });

        return result == "Success";
    }

    public async Task<bool> RemoveAsync(string token)
    {
        var result = await PostAsync(_apiUrl, new Dictionary<string, string>
        {
            { "action", "remove" },   // NOT "destroy" - that returns an SQL error
            { "token", token }
        });

        return result.Trim() == "success";
    }

    // Only the .m3u8 carries the token - segments inherit the session.
    // There is no expires parameter: the API has no query action, so nothing
    // authoritative exists to put in one.
    public static string BuildPlaylistUrl(string playlist, string token)
    {
        return string.Format("{0}?otp={1}", playlist, Uri.EscapeDataString(token));
    }
}

Usage, holding one token per session:

// Credentials come from configuration or a secret store - never from source control.
// One endpoint for every action; the trailing slash is required.
var otp = new WinkOtpClient("https://router.example.com/otp/api/",
                            Configuration["Wink:ApiUser"],
                            Configuration["Wink:ApiPass"]);

var token    = await otp.CreateAsync(300);   // 300 seconds = 5 minutes
var mintedAt = DateTimeOffset.UtcNow;      // the API will not tell you when this dies

var videoUrl = WinkOtpClient.BuildPlaylistUrl(
    "https://router.example.com/200/public/hls/WF05-333F-4D5C-E636-2937.m3u8",
    token);

// Later, well inside the lifetime you measured for your deployment:
await otp.ExtendAsync(token, 300);
mintedAt = DateTimeOffset.UtcNow;

// When the session ends - "remove", not "destroy":
await otp.RemoveAsync(token);

Code Examples

JavaScript Integration

The correct shape: the page calls your own endpoint under an authenticated session, and your server holds the credential and speaks to the appliance.

// Browser - holds no credential, talks only to your own backend
async function guidStatus(guid) {
    const res = await fetch('/api/forge-proxy.php', {
        method: 'POST',
        credentials: 'same-origin',              // your session cookie, not an API credential
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ command: 'guidstatus', payload: guid })
    });

    if (!res.ok) {
        throw new Error('Proxy request failed: ' + res.status);
    }

    return res.json();
}

guidStatus('WF05-1EDA-1C04-6E33-ABF9')
    .then(function (r) { console.log('Status:', r.data); })
    .catch(function (e) { console.error(e); });

The matching backend. It authenticates the caller first, allows only the commands this application is meant to expose, and adds the credentials itself:

<?php
// /api/forge-proxy.php - credentials live here, never in the browser
session_start();

// 1. Require a real, authenticated session. A header is not a session.
if (empty($_SESSION['user_id'])) {
    http_response_code(401);
    exit(json_encode(array('error' => 'Not authenticated')));
}

// 2. Allow-list the commands this application may issue. Never proxy arbitrary commands.
$allowed = array('version', 'guidstatus', 'inputstatus');

$body    = json_decode(file_get_contents('php://input'), true);
$command = isset($body['command']) ? $body['command'] : '';
$payload = isset($body['payload']) ? $body['payload'] : '';

if (!in_array($command, $allowed, true)) {
    http_response_code(403);
    exit(json_encode(array('error' => 'Command not permitted')));
}

// 3. Build the request server-side, escaping anything that came from the client.
$xml = sprintf(
    "<wink_api user=%s pass=%s><req id='1' command=%s>%s</req></wink_api>",
    quoteattr(FORGE_API_USER),          // from config/environment, not source control
    quoteattr(FORGE_API_PASS),
    quoteattr($command),
    htmlspecialchars($payload, ENT_XML1 | ENT_QUOTES, 'UTF-8')
);

$ch = curl_init('https://forge.example.com/api/');
curl_setopt_array($ch, array(
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $xml,
    CURLOPT_HTTPHEADER     => array('Content-Type: application/xml'),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_SSL_VERIFYPEER => true,     // leave on in production
    ));

$response = curl_exec($ch);
curl_close($ch);

$node = @simplexml_load_string($response);

header('Content-Type: application/json');
echo json_encode(array(
    'status' => $node ? (string) $node->resp['status'] : 'error',
    'data'   => $node ? trim((string) $node->resp)      : 'Malformed response',
));

function quoteattr($s) {
    return "'" . htmlspecialchars($s, ENT_XML1 | ENT_QUOTES, 'UTF-8') . "'";
}
?>

Python Integration

A server-side client. Values are escaped before they reach the XML, every call has a timeout, and certificate verification stays on:

import requests
import xml.etree.ElementTree as ET
from xml.sax.saxutils import escape, quoteattr


class WinkAPIError(Exception):
    pass


class WinkAPI:
    def __init__(self, host, username, password, verify_ssl=True, timeout=10):
        self.host = host
        self.username = username
        self.password = password
        self.verify_ssl = verify_ssl
        self.timeout = timeout
        self.api_url = f"https://{host}/api/"

    def execute_command(self, command, payload="", req_id="1"):
        # quoteattr/escape matter: a password containing ' or & would otherwise
        # break the document, and an unescaped payload could inject elements.
        xml_request = (
            f"<wink_api user={quoteattr(self.username)} pass={quoteattr(self.password)}>"
            f"<req id={quoteattr(str(req_id))} command={quoteattr(command)}>"
            f"{escape(str(payload))}"
            f"</req></wink_api>"
        )

        try:
            response = requests.post(
                self.api_url,
                data=xml_request.encode("utf-8"),
                headers={"Content-Type": "application/xml"},
                verify=self.verify_ssl,
                timeout=self.timeout,
            )
            response.raise_for_status()
        except requests.RequestException as exc:
            raise WinkAPIError(f"Request to {self.api_url} failed: {exc}") from exc

        try:
            root = ET.fromstring(response.text)
        except ET.ParseError as exc:
            raise WinkAPIError(f"Malformed response: {response.text[:200]}") from exc

        resp = root.find("resp")
        if resp is None:
            raise WinkAPIError(f"No <resp> element in response: {response.text[:200]}")

        return {
            "status": resp.get("status"),
            "command": resp.get("command"),
            "data": (resp.text or "").strip(),
        }


# Example usage - credentials come from the environment, not from source control
import os

api = WinkAPI(
    "forge.example.com",
    os.environ["WINK_API_USER"],
    os.environ["WINK_API_PASS"],
)

try:
    version = api.execute_command("version")
    print(f"API Version: {version['data']}")

    status = api.execute_command("guidstatus", "WF05-1EDA-1C04-6E33-ABF9")
    print(f"Stream Status: {status['data']}")
except WinkAPIError as exc:
    print(f"API call failed: {exc}")

cURL Examples

Basic Commands

# Get API version
curl -X POST https://forge.example.com/api/ \
    --cacert /path/to/appliance-ca.pem \
    --data-urlencode "<wink_api user='apiuser' pass='apipass'><req id='1' command='version'></req></wink_api>" \
    -H 'Content-Type: application/xml'

# Start all streams
curl -X POST https://forge.example.com/api/ \
    --cacert /path/to/appliance-ca.pem \
    --data-urlencode "<wink_api user='apiuser' pass='apipass'><req id='1' command='start'>all</req></wink_api>" \
    -H 'Content-Type: application/xml'

# Create OTP token (server-side only - apiuser/apipass never reach the browser)
# Keep the duration short for browser-facing use and renew with extend.
curl -d "apiuser=apiuser&apipass=apipass&action=create&duration=300" \
     -X POST https://router.example.com/otp/api/

Advanced Examples

# Create new input with full configuration
curl -X POST https://forge.example.com/api/ \
    --cacert /path/to/appliance-ca.pem \
    --data-urlencode "<wink_api user='apiuser' pass='apipass'>
        <req id='1' command='input_source'>
            <input title='Conference Room' 
                   desc='Main conference room HD camera' 
                   type='RTSP' 
                   path='rtsp://admin:password@192.168.1.100:554/stream1'
                   fps='30'
                   width='1920'
                   height='1080'
                   ptz_avail='1'
                   usrlat='41.8781'
                   usrlong='-87.6298'
                   enabled='1' />
        </req>
    </wink_api>" \
    -H 'Content-Type: application/xml'

Notes & Best Practices

API Versioning

• API methods maintain backward compatibility across minor versions
• Major version changes may introduce breaking changes
• Always verify API compatibility before firmware upgrades
• Test API calls on non-production systems first

Performance Considerations

• Batch operations when possible to reduce API calls
• Implement exponential backoff for retry logic
• Monitor API response times for system health
• Use connection pooling for high-frequency operations

Security Best Practices

• Mint OTP tokens server-to-server. API credentials stay on your server; the browser receives only a finished, short-lived stream URL. Never ship apiuser/apipass to the client or expose a public endpoint that mints tokens for any caller. See OTP Must Be Minted Server-to-Server and the Integrator Security Checklist.
• Require a real authenticated session on your token endpoint — a Referer/Origin header is not access control.
• Keep browser-facing tokens per-session, scoped as narrowly as possible, and short-lived.
• Put your own rate limiting and bot protection in front of your token endpoint; do not rely on WINK's limits as your abuse defense.
• Always use HTTPS for API communications
• Implement API-specific user accounts with minimal permissions
• Rotate API credentials regularly
• Log all API access for audit purposes, and alert on abnormal token-issuance volume
• Use shared keys for additional security layers

Integration Tips

• OTP expiry should match application session duration
• Start short and call extend for sessions still watching, rather than issuing long-lived tokens up front
• Create one OTP per viewer session, not one shared token per site
• Define API credentials identically on every Media Router so cluster-wide tokens validate everywhere
• Implement proper error handling for all API responses
• Cache GUID lookups to reduce API calls
• Use the built-in API testing tool for development

Customer Support

Contact Information

Support Requirements

When contacting support, please provide:

• Customer ID
• System serial number or license key
• Firmware version (from version API command)
• Specific API commands causing issues
• Error messages or unexpected responses
• Network topology if relevant

Additional Resources

• Developer Portal: Access code samples and SDKs
• Community Forum: Share experiences with other developers
• Training Videos: API integration tutorials
• Release Notes: Latest API changes and additions