Private Images and Slides
Open images and slides from your own private storage. All you need is a private link or a token. Paste it in, and the image opens.
Your browser reads the file straight from your storage. Nothing is uploaded, and nothing passes through our servers.
The viewer never asks for your AWS keys. If a page does, it is not us.
What You Need
You need one of two things:
- A private link. One link opens one file, for a limited time. This suits a slide in a cloud bucket such as Amazon S3.
- An address and a token. A token works like a password for your data. This suits a lab or company that runs its own image server, such as the Find Nuclei Data Server.
Make the link yourself with the AWS CLI, or ask whoever runs your storage.
Open a Private Slide
- Click Open Image and go to the From URL tab.
- Paste the link or address, then click Load from URL.

- If you have a token, the viewer asks for it. Paste it and click Connect. A private link does not ask.

The slide opens. Pan, zoom and annotate as with any other slide.

What to Expect
- No download. The viewer reads only the parts of the file you look at.
- Your token stays in the tab. It stays out of the address bar and out of links you copy. A reload keeps working. A new tab asks again.
- A private link is a key. Anyone who has it can open the file until it expires. Send it only to people who should see the slide.
- Sharing with a token. Copy the link and send it. Your colleague needs their own token.
- Access ends. When a link expires, the Access Denied window opens. A token will not help, so make or ask for a new link. When a token expires, the viewer asks for a new one.
- One link, one file. A slide made of many files, such as MRXS or DICOM, or an OME-Zarr folder, needs a token. A zipped
.ozxdataset is one file, so a private link works. - Annotation links. A link can carry the slide's annotation file too. Behind a token, the file opens when it sits on the same server as the slide. The viewer never sends your token anywhere else.
Make a Private Link With the AWS CLI
For a slide on Amazon S3, one command makes the link. Replace the bucket, the path and the region with yours:
aws s3 presign s3://your-bucket/pathology/CMU-1.svs --expires-in 28800 --region eu-central-1It prints a long https:// address. Send that to the person who needs the slide.
--expires-inis in seconds. 28800 is 8 hours. Without it, the link lasts 1 hour. The longest is 7 days.- A link made with temporary keys, such as an SSO login or a role, stops working when those keys expire, even if
--expires-inis longer. A role gives at most 12 hours, and only if the role allows it. Temporary keys of an IAM user give at most 36 hours. - The keys that make the link must be allowed to read the file.
- The bucket needs the CORS rule once. Without it, the browser blocks the read.
The same works for .ndpi, .scn, Philips .tiff, .czi, OME-TIFF and a zipped .ozx dataset. Each is one file. A slide made of many files, such as MRXS, needs a token instead.
A Link That Lasts 7 Days
Only the permanent access key of an IAM user makes a link that lasts the full 7 days. Use a separate IAM user that can only read the slides, never your own keys.
- In the IAM console, create a user, for example
slide-links. It needs no console access. - Give it one inline policy that allows reading the slide folder and nothing else:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::your-bucket/pathology/*"
}]
}- Create an access key for it (Security credentials, then Create access key) and save it as its own profile:
aws configure --profile slide-links- Make the link with that profile:
aws s3 presign s3://your-bucket/pathology/CMU-1.svs --expires-in 604800 --region eu-central-1 --profile slide-links604800 seconds is 7 days. To end every link early, deactivate or delete the user's access key. Each link made with it stops working at once.
Ask Your IT Team
If someone else runs your storage, copy this into an email or a ticket:
I would like to open a slide in Find Nuclei Viewer (https://find-nuclei.github.io). It runs in my browser and reads the file directly from our storage. Nothing is uploaded.
Please give me one of these:
- A time-limited presigned link to the file, if it sits on Amazon S3.
- The address of the file and a Bearer token, if it sits on a server that accepts one.
The storage must allow requests from https://find-nuclei.github.io (CORS) and must support range requests. Setup details: https://find-nuclei.github.io/docs/guides/remote-urls#what-the-server-needs
Image credits
The screenshots use CMU-1.svs from the OpenSlide test data, CC0, served from a test address. See Sample Data and Credits.
For Developers
The rest of this page is for developers building the viewer into their own app. The library ships hooks for the two common cases:
- Static credentials: a Bearer token, basic auth header, or any custom header. Use this for servers that accept a long-lived credential per request.
- Per-request signing: AWS SigV4 (or any signature scheme) for endpoints where every request needs its own cryptographic signature.
Both plug into the same HttpZarrStore. No store sub-classing, no monkey-patching.
Static Headers
For servers that accept a fixed Authorization header on every request:
import { HttpZarrStore, OmeZarrParser } from '@find-nuclei/viewer';
const store = new HttpZarrStore('https://lab-nas.example.com/data.zarr', {
headers: { Authorization: 'Bearer <token>' },
});
const parser = new OmeZarrParser(null, store);Headers are merged into every fetch the store makes: metadata files, range requests, chunk GETs.
AWS SigV4 (S3-direct via STS)
For S3 buckets where you want the viewer to fetch tiles directly from S3 without proxying every request through a server, use STS-scoped temporary credentials.
The viewer doesn't talk to AWS or know about IAM. Your backend mints short-lived credentials scoped to one image's S3 prefix; the viewer signs each request with them.
Backend contract
Your backend (any language, any framework) exposes an endpoint that:
- Authenticates the user (your auth, not the viewer's concern).
- Verifies the user has permission for the image.
- Calls
sts:AssumeRolewith an inline session policy limited to the one image's S3 prefix. - Returns the temporary credentials.
Example response shape (15-min TTL is the STS minimum):
{
"access_key_id": "ASIAEXAMPLE...",
"secret_access_key": "...",
"session_token": "...",
"expires_at": "2026-04-25T19:50:38+00:00",
"region": "eu-central-1",
"bucket": "my-private-bucket",
"prefix": "orgs/abc/images/xyz/"
}The session policy on the backend should be something like:
{
"Statement": [{
"Effect": "Allow",
"Action": ["s3:GetObject"],
"Resource": ["arn:aws:s3:::my-private-bucket/orgs/abc/images/xyz/*"]
}]
}A leaked token can only read the one image's tiles. It cannot list the bucket and cannot read other images.
Viewer setup
import {
HttpZarrStore,
OmeZarrParser,
createAwsSigner,
} from '@find-nuclei/viewer';
const initial = await fetch(`/api/v1/images/${imageId}/access-token`, {
method: 'POST',
headers: { Authorization: `Bearer ${cognitoJwt}` },
}).then(r => r.json());
// Hold the latest creds in a closure so refresh swaps them in place.
let creds = initial;
let pendingRefresh = null;
const REFRESH_AHEAD_MS = 2 * 60 * 1000;
const refreshIfNeeded = async () => {
const remaining = new Date(creds.expires_at).getTime() - Date.now();
if (remaining > REFRESH_AHEAD_MS) return creds;
if (pendingRefresh) return pendingRefresh;
pendingRefresh = (async () => {
const fresh = await fetch(`/api/v1/images/${imageId}/access-token`, {
method: 'POST',
headers: { Authorization: `Bearer ${cognitoJwt}` },
}).then(r => r.json());
creds = fresh;
return creds;
})().finally(() => { pendingRefresh = null; });
return pendingRefresh;
};
const signer = createAwsSigner({
getCredentials: async () => {
const c = await refreshIfNeeded();
return {
accessKeyId: c.access_key_id,
secretAccessKey: c.secret_access_key,
sessionToken: c.session_token,
expiresAt: c.expires_at,
region: c.region,
};
},
});
const directUrl =
`https://${initial.bucket}.s3.${initial.region}.amazonaws.com/` +
initial.prefix.replace(/\/$/, '');
const store = new HttpZarrStore(directUrl, {
signRequest: signer.signRequest,
});
const parser = new OmeZarrParser(null, store);After this, every fetch() the store issues is signed with SigV4 in the browser using crypto.subtle (native, hardware-accelerated). That covers .zattrs, .zarray, .zgroup, every chunk, and every range request. No proxy server sits in the per-tile path.
Refresh strategy
Refresh is request-driven, not timer-driven:
- Each request calls
signer.signRequest, which callsgetCredentials. getCredentialschecks how much TTL is left and returns cached creds if comfortable, or triggers one mint call if not.- Concurrent requests during a refresh share the same in-flight promise (the signer dedups internally as a second layer of safety).
No setInterval, no background work. If the user idles for 20 minutes, no API calls happen; the next interaction triggers exactly one refresh.
Custom signers
signRequest accepts any callback of shape:
type SignRequest = (
url: string,
init: RequestInit,
) => Promise<{ url: string; init: RequestInit }>;The store calls it before every fetch, gets back a possibly-rewritten URL and RequestInit, and uses those. Use this for:
- HMAC-signed URLs (custom auth schemes)
- CloudFront signed URLs that you generate per request
- Signed cookies (return
init.credentials = 'include'and let the browser send the cookie) - Anything else where the auth depends on the request itself
Whole-slide files
Pass signRequest from createAwsSigner to remoteFileStore. Every range request is signed the same way as an OME-Zarr read.
Your bucket's CORS rules must allow the Authorization, Range, x-amz-date, x-amz-security-token and x-amz-content-sha256 request headers.
Analysis bundles and label masks
An analysis bundle, or a run of several, can sit in private storage too. The same signer signs it. Hand the signer to the two loaders in an options object. signer is the one from Viewer setup, and runUrl is the URL of the folder that holds the run's manifest.json:
import { loadBundleFromURL, discoverRemoteLabels } from '@find-nuclei/viewer';
// The signer is the last parameter. The three before it keep their defaults.
const loaded = await loadBundleFromURL(
runUrl,
'run', // label id; the bundles of a run name their own labels
null, // object ID column: no override
undefined, // fetch
undefined, // Parquet reader
undefined, // label discovery
{ signRequest: signer.signRequest },
);
// The label masks below the same URL.
const { labels } = await discoverRemoteLabels(runUrl, {
signRequest: signer.signRequest,
});One signer covers every request: the manifests, the measurement tables and their sidecars, the search for masks, and the mask tiles. For a run, that includes each bundle in it.
Hand the signer over once. If you also pass signedFetch(signRequest) as the loader's fetch, the manifests, the sidecars and the measurement tables are signed twice. The search for masks takes the signer from the options only, so it is signed once.
signedFetch(signRequest), also from @find-nuclei/viewer, is for code that takes a fetch and no signer. It returns a fetch that signs each request first. Without a signer it returns the fetch you gave it, or the global one.
CORS
Whichever auth scheme you use, the server has to allow the viewer's origin and range requests. What the Server Needs has the rules and an S3 CORS rule to copy. A signed request also sends the Authorization, x-amz-date, x-amz-security-token and x-amz-content-sha256 headers, which "AllowedHeaders": ["*"] covers.