Shares
External, token-based access links to Assets or Folders. A share lets you grant a third party (a client, a customer, an anonymous recipient) time-limited or password-protected access to a store object without giving them an S-Launch account.
Scopes
| Scope | Reach |
|---|---|
store:read | Listing, reading, downloading shares; checking filters. |
store:write | Updating, patching, deleting share records. |
store:share | Creating share links and emailing them. |
| (none) | POST /api/share/get_access — used by unauthenticated recipients to redeem a share. |
The store:share scope is intentionally separate from store:write: a role can be allowed to modify share metadata without being allowed to mint new external links.
Endpoints
Create Share
POST /api/share/
Creates a new share record targeting an asset or folder, returning the share's token and access URL.
Required scope: store:share
Request body — ShareWriteCreate
Response 201 — ShareReadCreate
List Shares
GET /api/share/
Returns a page of share records.
Required scope: store:read · also accepts API key
Query parameters — standard pagination set; see Conventions › Pagination. Defaults: sort_by=created, sort_order=desc, hydrate=true.
Response 200 — ShareInDbCursorPage
Get Share Filter Metadata
GET /api/share/filters
Returns the filter/operator/sort options accepted by List Shares.
Required scope: store:read
Response 200 — open metadata object.
Get Share by ID
GET /api/share/{id}
Returns a single share record (the owner's view — includes statistics, expiry, recipients).
Required scope: store:read · also accepts API key
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Share ID. |
Response 200 — ShareRead
Update Share by ID
PUT /api/share/{id}
Replaces the share's mutable metadata (expiry, password, allowed recipients, etc.).
Required scope: store:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Share ID. |
Request body — ShareWriteReplace
Response 200 — ShareRead
Patch Share
PATCH /api/share/{id}
Partial share metadata update.
Required scope: store:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Share ID. |
Request body — ShareWriteUpdate
Response 200 — ShareRead
Delete Share by ID
DELETE /api/share/{id}
Revokes the share — its token immediately stops resolving.
Required scope: store:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Share ID. |
Response 204 — empty.
Get Access to Share
POST /api/share/get_access
The recipient-facing endpoint. Anonymous (unauthenticated) callers submit the share token plus any required password to obtain a time-limited access response.
Required scope: none
Request body — ShareAccessRequest — the token and optional password.
Response 200 — ShareAccessResponse
TIP
This is the only Shares endpoint reachable without authentication. Treat it as a public surface — never expose owner-side share IDs through it; this endpoint operates on the opaque share token only.
Download Share by Token
GET /api/share/download/{token}
Downloads the underlying asset or folder via the share token. Honors any access restrictions configured on the share (expiry, max downloads, etc.).
Required scope: store:read — note that recipient flows typically pair this with Get Access to Share first to obtain a short-lived credential; consult your tenant's specific share-redemption pattern.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes | Share token. |
Response 200 — binary stream of the underlying object.
Send Share Email
POST /api/share/send_email
Emails the share link to one or more recipients. The server formats the message using the active mail template.
Required scope: store:share
Request body — ShareEmailRequest
Response 200 — confirmation payload.
See also
- Assets and Folders — what a share points at.
- Mail Templates — the template used when Send Share Email runs.
- Asset Store › Workflow — end-to-end upload + share example.