Script tokens
Script tokens let a content provider control access to particular movement scripts. They can simplify playback for users and give providers options for access duration, subscription entitlements, and distribution of the underlying script files.
A provider can supply a funscript-shaped script-token file that a supported player uses in place of the corresponding funscript. The file represents access to a script; the provider determines the access policy and how the file or URL reaches the player. The script-format reference covers ordinary movement data.
Distinguish content access from API authentication
| Concept | Purpose |
|---|---|
| Script token | Represents access to script content under the provider's policy. Access and expiry state are handled server-side. |
| API client token | Authenticates requests to a particular API. Its scope and permissions come from that API's issuance contract. |
A script token does not replace the Application ID or client token required for Handy REST device control. Device requests still need their own API authentication and device connection key.
A token as a file or URL
The same script access can be supplied as a file or reached through a URL:
| Form | How it is used |
|---|---|
| Script-token file | Download and select it alongside a video, where the player normally accepts a funscript. The file carries access to the script, rather than the script's ordinary movement points. |
| Token URL | Supply it to a supported server-side playback flow. The server resolves the token to the script it authorizes. |
Uploading a valid script-token file to Hosting API v2 returns a token URL, rather than the ordinary download URL containing a script's SHA-256 hash. Uploading the file does not turn the token into an unrestricted copy of the movement data.
Treat issued files and URLs as opaque and pass them through unchanged. The client does not need to decode a token file, construct a token URL, or add a new token wrapper.
During server-side script loading:
- The server retrieves the file from the supplied URL.
- If it identifies the file as a script token, it locates the actual script the token grants access to.
- It checks token validity and authorization for the intended device.
- When those checks pass, it sends the authorized script's movement data to the device. Failed checks prevent that delivery.
Use a token file like a funscript
The intended user experience stays familiar:
- Download a video and its matching script-token file from the provider.
- Open a supported player and select the local video.
- Select the token file where you would normally select a funscript.
- Connect the intended device and press Play.
A compatible player lets users watch downloaded videos outside the provider's website while the provider controls the script-access policy.
What the player handles
The player handles file hosting and playback setup in the background. Use Hosting uploads and Handy REST HSSP playback for the concrete API requests.
Any URL used by the backend to retrieve the token file must be accessible over the internet. A URL on a private network will not work for that retrieval.
Plan for internet access when obtaining or resolving access, even when the video and token file have already been downloaded. Compatibility requires a supported device and a token-capable online playback flow. A player that only interprets action values locally needs the appropriate token-resolution integration before it can offer this experience.
Common use cases
- Integrated playback: associate a video identifier with its matching script so a player can offer motion without asking the user to manage two separate files.
- Subscriber access: authorize script playback according to the provider's subscription or other entitlement rules.
- Time-limited access: give a playback session a defined validity period and manage that access through the provider integration.
- Free playback with restricted downloads: offer a script at no charge while limiting access to the raw file.
- Open distribution: use the same integrated playback experience while also allowing users to download the script.
- Script improvements: a provider can deliver updated script content through the token-based workflow without asking users to replace a previously downloaded token file, subject to the provider's content policy.
These choices address different needs. The price of playback and permission to download or edit a script are separate provider decisions.
Open and closed script distribution
With open distribution, the provider allows access to the script file. With closed distribution, it offers playback while restricting access to that file. Script tokens can support either policy; using tokens does not by itself require a closed distribution model.
When the provider allows editing the movement itself, use the authorized script content rather than the token file.
Content and device access
Script access is issued for the intended content and device. If the user changes devices, obtain access for the new target through the provider's supported flow. Selecting a token file does not authorize it for every device or grant access to other scripts.
The playback client does not need the provider's account credentials or management permissions to use the access it has been given.
Manage access over time
Access can expire or be revoked under the provider's policy. Follow the provider's supported flow to obtain fresh access when needed. Script-access validity has its own rules, separate from an API client token's lifetime.
Download-link lifetime and playback validity
The download URL and the token have separate lifetimes:
| Lifetime | Meaning |
|---|---|
| Download-link lifetime | How long the URL remains available for downloading the token file. |
| Playback validity | How long the token authorizes access to the script, subject to any other provider restrictions. |
A saved token file remains subject to token expiry and provider revocation. An expired download link can prevent obtaining the file even while the token's access period has time remaining. Downloading a file does not remove its access restrictions.
Explain access failures to users
Use the service's reported outcome to explain an unavailable download link, a device that needs to reconnect, or script access that has expired or been revoked. Offer the provider's supported route to obtain fresh access after checking entitlement again. Keep the local video/file-selection workflow intact; an access failure does not require inventing a different script format.
Fresh provider authorization is a separate action from retrying a failed Hosting request. Hosting's TOKEN_EXPIRED outcome is terminal for that client flow: do not automatically retry the same upload or invent a renewal procedure. See Hosting error handling for response details.
Offer playback without a script download
A provider can also offer playback within its own integration without supplying a script-token file or an ordinary script download to the user. Keep content preparation on your application's backend and let the Handy servers deliver movement data to the device.
| Approach | How it works |
|---|---|
| Stream API and STREAM | Your backend stores the script through the Stream API. Handy REST's STREAM setup selects the returned stream_ref, so the player does not need the original funscript, CSV or source URL. |
| Backend HSSP setup | Your backend calls HSSP setup with the script URL. The Handy API server retrieves the script; the browser or player does not need that URL. |
For example:
- The client asks your backend to play selected content on the target device.
- Your backend checks the user's entitlement, selects the script or stored stream, and completes the matching Handy REST setup.
- After setup succeeds, the client can use that protocol's playback controls, or your backend can forward those controls too.
For STREAM, you can instead give the client only stream_ref and let it perform setup. If you also want to keep that reference on your backend, perform STREAM setup there. Keep the stream's data/editor keys on the backend. HSSP's script URL must still be reachable by the Handy API server; a private-network-only URL will not work.
Handy REST device requests use an Application ID or client token and device addressing, even when sent from your backend. An Authentication Key remains for the operations that accept it, such as client-token issuance; it does not authorize device setup or playback.
These approaches keep the raw script out of the normal client download flow. They do not create script tokens or automatically apply script-token device binding, expiry or revocation. Your backend enforces its own content-access policy.