#downloadAccess

Read or replace the download policy for an app. A policy either allows public downloads or restricts downloads to specified IPv4 and IPv6 addresses or networks. Apps without a configured policy default to public access.

See Restricting downloads by IP address for setup, proxy configuration, and automatic-update considerations.

#Authentication and permissions

Both methods use the shared API authentication rules.

• GET: the app owner and collaborators can read the policy, including those with read-only access.
• PUT: only the app owner can replace the policy.

#Read the policy

GET /v1/downloadAccess?appId={appId}
Authorization: Bearer <access-token>

The required appId query parameter is your ToDesktop app ID.

curl "https://api.todesktop.com/v1/downloadAccess?appId=your-app-id" \
  -H "Authorization: Bearer $TODESKTOP_ACCESS_TOKEN"

Returns HTTP 200 with the saved policy. For an app with no configured policy:

{
  "appId": "your-app-id",
  "downloadAccess": { "mode": "public" }
}

#Replace the policy

PUT /v1/downloadAccess?appId={appId}
Authorization: Bearer <access-token>
Content-Type: application/json

Supply the complete policy as the JSON body, as shown below. Each PUT replaces the previous policy, including the entire address list.

#Restrict downloads

Contact ToDesktop to enable private downloads for your app before setting an allowlist. Until setup is complete, the API returns 409 private-storage-required.

Replace the example addresses below with the public source addresses that your network or proxy uses to reach ToDesktop:

curl -X PUT "https://api.todesktop.com/v1/downloadAccess?appId=your-app-id" \
  -H "Authorization: Bearer $TODESKTOP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"mode":"ipAllowlist","allowedCidrs":["203.0.113.10","2001:db8::/48"]}'

Returns HTTP 200 with the normalized policy:

{
  "appId": "your-app-id",
  "downloadAccess": {
    "mode": "ipAllowlist",
    "allowedCidrs": ["203.0.113.10/32", "2001:db8::/48"]
  },
  "cacheInvalidation": "requested"
}

#Restore public downloads

curl -X PUT "https://api.todesktop.com/v1/downloadAccess?appId=your-app-id" \
  -H "Authorization: Bearer $TODESKTOP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"mode":"public"}'

The response contains downloadAccess: { "mode": "public" } and cacheInvalidation: "requested". This restores public access through ToDesktop's download URLs.

#Policy fields and limits

Accepts IPv4/IPv6 addresses and CIDR ranges, such as 203.0.113.0/24. Addresses are normalized automatically.

#Propagation and retries

Policy changes may take two hours to take effect everywhere. A successful PUT with cacheInvalidation: "requested" confirms the policy was saved and a refresh was requested. GET returns the saved policy, which may not yet be active everywhere. Downloads already in progress can complete.

If the API returns 503 with reason invalidation-failed, the policy was saved, but the refresh failed. Retry the same PUT even if GET shows the new policy.

Retry only the policy you still want to apply: an older PUT can overwrite a newer change. Follow the guide's verification steps before relying on a new restriction.

#Errors

Errors have this shape:

{
  "error": {
    "reason": "private-storage-required",
    "message": "Private artifact storage must be configured before restricting this app."
  }
}

For authentication and permission errors, see the shared error handling reference.