Access purchased assets

This guide explains how to retrieve secure access links for purchased digital assets after an order has been successfully completed.

HL Connect does not stream or proxy asset files directly. Instead, it provides short-lived secure URLs that grant temporary access to purchased content.

Overview

Access to assets is only available after a purchase reaches the COMPLETED state.

The vendor completes a sale on their side
The purchase is registered and fulfilled asynchronously
The order reaches COMPLETED
The vendor requests secure access URLs
The customer downloads or views the asset

Access URLs are generated on demand and are short-lived. They must be requested at the moment the customer is ready to download or view the asset, and used immediately. See Link lifetime and expiration below.

Client API Token

Prerequisites

Before requesting access URLs, ensure that:

The purchase order exists
The order status is COMPLETED
The order was not canceled

Attempting to access assets for orders in other states may result in an error.

Download the asset

Use this endpoint to retrieve a secure URL for downloading the purchased asset file (PDF, audio, media file, etc.).

The returned URL:

Provides direct access to the file and requires no additional authentication
Expires — the response carries the exact moment in expires_at
Must be requested on demand and used immediately, not stored or pre-sent

Do not cache or persist this URL. Request it the moment the customer initiates the download and redirect them straight to it. See Link lifetime and expiration.

View the asset online

Some assets support online viewing instead of direct download (for example, sheet music or interactive viewers).

This endpoint returns a secure URL suitable for embedding or redirecting the user to an online viewer.

Link lifetime and expiration

Download and view URLs are short-lived. Every response carries the moment they stop working as a UNIX timestamp: expires_at on the download-URL and view-URL responses, and url_expires_at on each line of the order. Read that field rather than assuming a fixed duration — it is shorter for some asset types. Until that moment there is no limit on how many times a URL may be used.

The endpoint automatically re-issues a new, valid URL on every call, including after a previous link has expired, as long as the order is still COMPLETED. No separate refresh call is required. A link the customer opens after it expired answers 410 Gone, unless your account has its own "link expired" page configured.

Access lifecycle

Asset access is tightly coupled to the order lifecycle.

Order status	Access behavior
`PROCESSING`	Access not available
`COMPLETED`	Access URLs can be generated
`FAILED`	No access available
`CANCELED`	Previously granted access is revoked

Vendor-initiated revocation

If a refund, dispute, or other business event occurs on the vendor side, access to the asset can be revoked.

After cancellation:

Previously issued URLs may stop working
New access URLs can no longer be generated
The order transitions to CANCELED

Common access pattern

sequenceDiagram
    participant Vendor
    participant HL as HL Connect
    participant Customer

    Vendor->>HL: GET /purchase/download-url
    HL-->>Vendor: Secure URL
    Vendor-->>Customer: Redirect / link
    Customer->>HL: Download / View asset

Error handling

Asset access endpoints use standard HTTP status codes:

401 — missing or invalid access token
404 — order or asset not found
409 — order state does not allow access
5xx — internal or fulfillment errors

Errors are returned in a structured JSON format and are safe to log.

Summary

Access is only available after COMPLETED
Use secure URLs for download or online viewing
URLs are short-lived; request a fresh one each time and use it immediately
Never store or pre-send a URL
Call the endpoint again to get a fresh URL; the vendor can revoke access at any time