Skip to content
Share2Us

Mint a short-lived gateway unlock token for a share your own account owns. Session-only (never an API token).

POST
/v1/shares/{id}/unlock
curl --request POST \
  --url https://api.share2.us/v1/shares/example/unlock \
  --header 'Authorization: Bearer <token>'

The fourth layer of ADR-022’s recipient verification, for the one party who cannot use the other three. An owner is admitted by the gateway (ShareOwnerHasEmail), but every way of REACHING that gate is browser-shaped: the invite link arrives in a recipient’s mailbox, the session hop is a portal form-POST, and the emailed code needs an HTML form. Every CLI download path is anonymous, so an owner signed in on the CLI is refused their own private file.

This mints the SAME signed token the other layers produce, bound to the CALLER’S OWN email (taken from the auth context, never the request body) and to this share, to be replayed as the gateway’s ?u= parameter. The gateway is unchanged.

Minting is not an access: expiry, revocation, blocks, view/download limits and the download password are all still enforced at the gateway on the request that follows, so a token for a revoked share opens nothing. A share owned by another account returns 404 rather than 403, so the endpoint cannot confirm that a share exists. Rate-limited per account. A personal API token is refused with 403 session_required: a long-lived credential that could mint gateway unlocks would become a download credential for every private share on the account.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Responses

Section titled “Responses”

200

Section titled “200”

Unlock token minted.

Media typeapplication/json
object
token
required

Pass to the gateway as ?u=<token> on the share URL.

string
expires_in
required

Seconds until the token expires (short — it is replayed immediately).

integer
Examplegenerated
{
  "token": "example",
  "expires_in": 1
}

default

Section titled “default”

Standard error envelope.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
request_id
required
string
Example
{
  "error": {
    "code": "quota_exceeded"
  }
}