Skip to content

Signed and session URLs for safe sharing

Sometimes you want to share a file with someone without giving them long‑lived access.

That's what signed URLs are for.

You can also share session URLs for interactive browsing of a specific folder tree.

This document explains both and when to use each.

Understanding Sites URLs shows where these URLs sit among the other Site URL types.

A signed URL is typically:

  • time‑limited
  • permission‑limited (r for read or rw for read/write)
  • a credential that anyone can use until it expires

Signed URLs vs Session URLs: Quick comparison

Feature Signed URL Session URL
Purpose Direct access to a specific resource Interactive browsing of a folder tree
UX Direct request to the target URL Full ECMWF file browser with drag/drop
Scope The signed target URL Directory + descendants
Permission r (read) or rw (read/write) r (read) or rw (read/write)
Best for Email attachments, reports, one-off shares Temporary folder access, collaboration
Example use "Here's your report.pdf" "Review all files in /ProjectA/ for this week"

When to use signed URLs

Use signed URLs for a specific file or resource when:

  • you need to share a link with an external party
  • you want to avoid adding user/group access permanently
  • you want an expiring link for a specific file

Use r for downloads. Use rw only when the recipient must change the target resource.

Examples:

  • Email a report: Generate a read-only signed URL for reports/2024-Q2-summary.pdf, set it to expire in 48 hours. Paste the link in an email. The recipient can download it until it expires without a site account.
  • Share model output with a partner: Create a signed URL for a single netCDF file at outputs/model_v3.2_forecast.nc, set to expire in 72 hours. The partner downloads the file, not the whole folder.
  • Temporary file download: Give a colleague a temporary link to archive/backup_2024_06.tar.gz without adding site access. Use a read-only signed URL with a short expiry.

When to use session URLs

Use session URLs when:

  • you need to share a folder for interactive browsing
  • you want users to see a file listing and download/upload multiple items
  • you want temporary drag-and-drop upload capability (if rw)
  • you want to avoid adding permanent site access or login accounts

Real-world examples:

  • Shared project folder: Your team is collaborating on /Incoming/ProjectA/. Create a rw session URL with 1-week expiry. Team members can upload drafts, download latest versions, and navigate the folder—all without site accounts.
  • Client review window: A client needs to review files in /Deliverables/2024/. Create a read-only r session URL, expires in 10 days. Client browses, downloads, but can't modify.
  • Temporary data staging: Your pipeline deposits output in /staging/batch_001/. Create a session URL for your ops team to inspect, with 48-hour expiry. The folder has 100+ files; a single signed URL wouldn't help.
  • Partner feedback: External consultant needs to review and annotate files in /Analysis/Proposal_v3/. Create rw session URL (48 hours). Consultant can download files, upload revised versions, without a login.

Generating a signed URL

The quickest way is in the file browser itself: right-click a file or folder and choose Link actions → Generate signed URL, then pick permission and expiry.

For automation, call the Hub API (v1 and v2 expose the same endpoints), which signs with the site's master token:

The Hub API exposes an endpoint like:

  • POST /hub/api/v1/sites/<space>/<site>/signed-urls/

You’ll provide values like:

  • permission (for example r for read)
  • duration (seconds)
  • url (the target URL you want to sign)

See the Hub API specification for the endpoint details. Only site administrators can create these links.

Example using curl

HUB_TOKEN="..."   # OIDC access token for a site administrator

curl -H "Authorization: Bearer ${HUB_TOKEN}" \
  "https://<domain>/hub/api/v1/sites/<space>/<site>/signed-urls/" \
  -d "permission=r" \
  -d "duration=8400" \
  -d "url=https://<domain>/<space>/<site>/path/to/file"

The response should include a new URL.

Generating a session URL

For automation, session URLs are generated via the Hub API (v1 and v2 expose the same endpoint):

  • POST /hub/api/v1/sites/<space>/<site>/session-urls/

You'll provide:

  • identifier (required; who/what is using this session)
  • permission (for example r for read, rw for read/write)
  • duration (seconds)
  • path (optional; directory scope, defaults to /)

Example using curl

HUB_TOKEN="..."   # OIDC access token for a site administrator

curl -H "Authorization: Bearer ${HUB_TOKEN}" \
  "https://<domain>/hub/api/v1/sites/<space>/<site>/session-urls/" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "projecta_team",
    "permission": "rw",
    "duration": 604800,
    "path": "/Incoming/ProjectA/"
  }'

The response includes a session URL. Users can open it in a browser for interactive file browsing.

Using the browser UI

  1. Right-click a file or folder in the ECMWF file browser.
  2. Select Generate session URL from the context menu.
  3. Choose permissions and expiry. The scope defaults to the selected file's parent folder, or to the selected folder.
  4. Copy and share the URL.

Admin note: The same right-click Link actions menu also includes Create symlink, which opens a dialog to create a symlink path pointing to the selected file or folder.

Session URL technical details

Session URLs provide temporary, browser-based access to the ECMWF-style file listing page, with optional write capabilities depending on permission.

URL pattern:

  • /<space>/<site>/s/session/{token}

The generated link may include the scoped directory after the token, so it opens at that directory. The token payload sets the allowed scope; changing the URL path cannot grant access outside it.

Token payload fields:

  • path: scope root (defaults to / when not provided)
  • expiration: unix epoch expiry
  • permission: r or rw
  • identifier: mandatory label used for session attribution

Scope rules:

  • descendants of path are allowed
  • sibling-prefix paths are rejected (for example, /Incoming/ProjectAB/ is not inside /Incoming/ProjectA/)

Permission rules:

  • r: read-only (view and download)
  • rw: read-write (drag-and-drop upload, folder creation, and file editing)

Sharing best practices

For signed URLs:

  • Use for single-file downloads (reports, datasets, archives).
  • Prefer short durations (hours, not days).
  • Treat them as credentials; anyone with the link can use it until it expires.
  • You cannot revoke one signed URL. A site administrator can rotate the site master token to invalidate all signed URLs, session URLs, and HTTP access tokens for that site.

For session URLs:

  • Use for folder access and collaboration.
  • Prefer r (read-only). Use rw only when users need to upload or change files.
  • Set expiry based on the task: 24 hours for quick reviews, up to 1 week for ongoing collaboration.
  • Restrict the path scope to the smallest folder needed (e.g., /Incoming/ProjectA/ not /Incoming/).
  • You cannot revoke one session URL. A site administrator can rotate the site master token to invalidate all session URLs, signed URLs, and HTTP access tokens for that site.

Common problems

  • 403 when generating: you’re not a site admin.
  • 410 / archived: the site is disabled/archived and can’t issue new links.
  • 404 when using: the target URL might be wrong, or the resource might no longer be available.