Refresh share access

Resolve one file under an active share. View permission returns a short-lived signed viewer URL; download permission returns the public download address.

Outcome

Resolve one file under an active share. View permission returns a short-lived signed viewer URL; download permission returns the public download address.

Before you start

This handler is public. Discover the exact catalog action and its input before use; no workspace membership is granted by a public release or share URL.
A public sharing route remains confined to the supplied share and file; release downloads remain confined to desktop/releases.
Authorize the described effect or private-data export before passing CLI --confirm or MCP confirm:true. GET listing/search can persist derived data; HTTP method alone does not establish a read-only action.

Discover the target

topolo whoami --json
topolo actions get app_topolo_bytes.shares.refresh_session --detail --json
topolo actions get app_topolo_bytes.shares.list --detail --json

Request

POST /api/shares/refresh-session

Save action input as payload.json. The reviewed plan separates path identifiers, query fields and the HTTP body.

Inspect and test this action in the signed action console. A test response still requires the verification below.

Input fields

Field	Required	Type	Constraints
`shareId`	Required	string	{"minLength":1}
`fileKey`	Required	string	{"minLength":1}

Exact input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "shareId": {
      "type": "string",
      "minLength": 1
    },
    "fileKey": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "shareId",
    "fileKey"
  ],
  "additionalProperties": false
}

Effects

Returns a share-bound URL after checking share validity and membership of the supplied file key. This public endpoint does not grant workspace membership.

Interpret the response

This response does not return a guaranteed canonical target identifier. Keep the discovered request context and interpret its documented values without inventing a resource id.

Use the returned URL only for the specified share/file and its lifetime. Preserve exact errors for missing, expired or unauthorized share access.

The schema describes supported success fields; optional metadata and integration-dependent values may vary. Errors have the exact shapes shown in refused examples.

Success schema:

{
  "type": "object",
  "required": [
    "success",
    "url"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "url": {
      "type": "string"
    },
    "expires": {
      "type": "number"
    }
  }
}

Worked examples

Actual exported Worker handlers with local Miniflare R2/KV. Auth, workspace grants, R2 multipart, notification, usage and semantic integrations are simulated at their configured test boundaries. Synthetic ids, timestamps and signed URLs confer no live access. No deployed provider outcome, external delivery or live grant is established. Upload-session credential values are explicitly redacted; binary responses use the tested SDK transport envelope. Replace synthetic identifiers through credential-scoped discovery. Refused scenarios document failure boundaries; they are not successful workflows.

Successful request

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{
  "shareId": "333f3201dbca40cb8ab2d5e2e036fd8e",
  "fileKey": "dl.pdf"
}

CLI:

topolo actions validate app_topolo_bytes.shares.refresh_session --data @payload.json --json
topolo actions plan app_topolo_bytes.shares.refresh_session --data @payload.json --json
topolo actions call app_topolo_bytes.shares.refresh_session --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_bytes.shares.refresh_session",
    "input": {
      "shareId": "333f3201dbca40cb8ab2d5e2e036fd8e",
      "fileKey": "dl.pdf"
    },
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "success": true,
  "url": "https://bytes-api.test.local/share-download/333f3201dbca40cb8ab2d5e2e036fd8e/0"
}

HTTP 200. Use the returned URL only for the specified share/file and its lifetime. Preserve exact errors for missing, expired or unauthorized share access.

Another supported request

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{
  "shareId": "3112efbcbb2747b380ad28936f5c0234",
  "fileKey": "refresh.png"
}

CLI:

topolo actions validate app_topolo_bytes.shares.refresh_session --data @payload.json --json
topolo actions plan app_topolo_bytes.shares.refresh_session --data @payload.json --json
topolo actions call app_topolo_bytes.shares.refresh_session --data @payload.json --confirm --json

MCP tool and arguments:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_bytes.shares.refresh_session",
    "input": {
      "shareId": "3112efbcbb2747b380ad28936f5c0234",
      "fileKey": "refresh.png"
    },
    "confirm": true
  }
}

Captured local response · HTTP 200:

{
  "success": true,
  "url": "https://bytes-api.test.local/share-download/3112efbcbb2747b380ad28936f5c0234/0?session=eyJzaGFyZUlkIjoiMzExMmVmYmNiYjI3NDdiMzgwYWQyODkzNmY1YzAyMzQiLCJmaWxlS2V5Ijoib3JnYW5pemF0aW9ucy9vcmdfYWNtZS93b3Jrc3BhY2VzL3dvcmtzcGFjZV9hY21lL3JlZnJlc2gucG5nIiwic2Vzc2lvbklkIjoiNWM3ZWRjMDA0YTM4NGM4ODg3YzQyOWQ5MzIwMjdkNmUiLCJpc3N1ZWRBdCI6MTc5MTA3OTA3NTg4NCwiZXhwaXJlcyI6MTc5MTA3OTEwNTg4NH0.c8f4123b25bafda17317cf4af3102fb551d8b45b7ef72002997230c524b06462",
  "expires": 1791079105884
}

HTTP 200. Use the returned URL only for the specified share/file and its lifetime. Preserve exact errors for missing, expired or unauthorized share access.

Refused request · HTTP 400

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_bytes.shares.refresh_session --data @payload.json --json
topolo actions plan app_topolo_bytes.shares.refresh_session --data @payload.json --json

Captured local response · HTTP 400:

{
  "success": false,
  "error": "Share ID and file key required"
}

HTTP 400. This request was refused; preserve the exact response and correct its cause before retrying.

Refused request · HTTP 404

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{
  "shareId": "nope",
  "fileKey": "whatever.txt"
}

CLI:

topolo actions validate app_topolo_bytes.shares.refresh_session --data @payload.json --json
topolo actions plan app_topolo_bytes.shares.refresh_session --data @payload.json --json

Captured local response · HTTP 404:

{
  "success": false,
  "error": "Share link not found or expired"
}

HTTP 404. This request was refused; preserve the exact response and correct its cause before retrying.

Refused request · HTTP 403

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{
  "shareId": "ec32fb7b3b0f43ef8df130bdaa878e58",
  "fileKey": "not-in-share.pdf"
}

CLI:

topolo actions validate app_topolo_bytes.shares.refresh_session --data @payload.json --json
topolo actions plan app_topolo_bytes.shares.refresh_session --data @payload.json --json

Captured local response · HTTP 403:

{
  "success": false,
  "error": "File not included in this share"
}

HTTP 403. This request was refused; preserve the exact response and correct its cause before retrying.

Verify the result

Use the returned URL only for the specified share/file and its lifetime. Preserve exact errors for missing, expired or unauthorized share access.

Errors and recovery

Share ID and file key required (HTTP 400): Correct the exact fields using the discovered input schema and prerequisites. Refused input examples demonstrate errors and must not be executed as successful workflows.
Share link not found or expired (HTTP 404): Discover the existing file, share or release in the intended scope. A missing or inaccessible target is not authorization to create a replacement.
File not included in this share (HTTP 403): Verify the pinned organization, granted workspace resource and required application permission. Inspect the exact refusal before requesting narrower access; never switch scope to bypass the denial.

Authentication, the action-input validator or resource middleware can refuse a request before this handler. Preserve the exact request id, error and selected credential context. The fixtures establish no live credentials or configured provider.

Recovery boundary

No response identifier is minted. Revoke the owning sharing link separately if its access must end.

List sharing links: Read a page of sharing records visible in the selected workspace. Only accessible stored records appear; the response redacts stored passwords.

Evidence

Actual exported Worker handlers with local Miniflare R2/KV. Auth, workspace grants, R2 multipart, notification, usage and semantic integrations are simulated at their configured test boundaries. Synthetic ids, timestamps and signed URLs confer no live access. No deployed provider outcome, external delivery or live grant is established. Upload-session credential values are explicitly redacted; binary responses use the tested SDK transport envelope. Capture digests and test scenarios are retained in the source fixture records.

Refresh share access

Outcome

Before you start

Discover the target

Request

Input fields

Effects

Interpret the response

Worked examples

Successful request

Another supported request

Refused request · HTTP 400

Refused request · HTTP 404

Refused request · HTTP 403

Verify the result

Errors and recovery

Recovery boundary

Related actions

Evidence