Read public share links

A public share link is created in Nucleo (in Assets, Share > Public link) and opens its files to anyone who has it, without a Nucleo account or an API key: the token in the link is the access. The share page your recipients see reads the files with these calls, and a program can do the same (base https://api-catalog.nucleoplatform.com/api/dam/v1):

An unknown token answers 404, an expired link 410. Each address can make 600 requests a minute to one link.

Until you prove the password, every call on a protected link answers 401 with code: password_required and passwordRequired: true. The password goes only in a header or in the body of unlock, never in the URL:

1. Session (recommended). POST /share/{token}/unlock with {"password": "…"} returns data.session and data.maxAge (3600 seconds). Send it as X-Share-Session on the next calls, file and zip downloads included. It is valid for one hour and only for that link, and changing the link's password ends it.
2. Header. X-Share-Password: <password> on each call. Every call counts as an attempt, so prefer the session for more than one call.

SESSION=$(curl -s -X POST https://api-catalog.nucleoplatform.com/api/dam/v1/share/$TOKEN/unlock \
  -H "Content-Type: application/json" \
  -d '{"password": "the password you received"}' | jq -r .data.session)

curl https://api-catalog.nucleoplatform.com/api/dam/v1/share/$TOKEN \
  -H "X-Share-Session: $SESSION"

The password in the query string (?password=) is no longer accepted: the call answers 401 password_required as if no password had been sent. A password in a URL ends up in access logs, in the browser history and in the Referer header.

Wrong passwords are limited. A link accepts 10 wrong passwords a minute from the same address and 50 an hour from all addresses together. Past either limit it answers 429 too_many_attempts with Retry-After (in seconds) — even to the right password — until the window ends. Calls with a valid X-Share-Session are not affected, so whoever already unlocked the link keeps working.