Skip to main content
By default, your private aggregator serves your content to anyone who knows the URL. Restricted mode locks it down — every request must carry an access token before content is served. This is useful for gating downloads behind authentication, building signed-URL systems, or protecting premium content.

​
Enabling Restriction

Navigate to Settings → Aggregator and toggle Require authentication. Choose the access mode that fits your use case.

​
Access Modes

The restrictedMode field controls how clients present their access token. Use your Tusky API key as the token.

​
Header (default)

The client sends the Api-Key header with every request: 
curl https://myproject.mytusky.xyz/v1/blobs/abc123 \
  -H "Api-Key: YOUR_API_KEY"
Best for: Server-to-server communication, backend services, the Tusky SDK. The SDK passes this header automatically when configured with an API key.

​
Query parameter

The client appends ?api-key= to the URL: 
https://myproject.mytusky.xyz/v1/blobs/abc123?api-key=YOUR_API_KEY
Best for: Browser contexts where you cannot set custom headers — <img> tags, <video> sources, direct download links, or window.open() calls. 
<img src="https://myproject.mytusky.xyz/qp_abc123?api-key=YOUR_API_KEY" />
Query parameter tokens appear in browser history, server logs, and referrer headers. Use short-lived or scoped API keys when using this mode. Never expose a full-permissions key in client-side HTML.

​
Path prefix

The client embeds the token at the start of the URL path: 
https://myproject.mytusky.xyz/{accessToken}/v1/blobs/abc123
For example: 
curl https://myproject.mytusky.xyz/YOUR_API_KEY/v1/blobs/abc123
Best for: CDN configurations that route on path rather than query string, or presigned-URL-style access patterns where the token is baked into a shareable link.
All three modes use the same access token — your Tusky API key. You can create a scoped key with only files:read permission specifically for aggregator access. See API Keys for the full scopes reference.

​
Access Mode Comparison

ModeToken locationUse case
headerApi-Key: request headerServer-side, SDK, secure clients
query?api-key= URL parameter<img> tags, direct browser links
path/{token}/v1/blobs/... URL prefixCDN path routing, presigned links

​
Scoped Keys for Aggregator Access

Create a read-only API key to limit the blast radius if the token is ever exposed:
1

Create a scoped key

Go to dashboard.tusky.io/account/api-keys and create a new key. Grant only the files:read scope.
2

Configure your aggregator

Enable restricted mode with your preferred access mode.
3

Use the scoped key as the token

Distribute the scoped key to clients or embed it in signed links. If the key is compromised, revoke it and create a new one — it cannot write, delete, or modify anything.

​
What’s Next

API Keys

Create scoped keys for aggregator access.

Custom Domains

Serve restricted content through your own branded domain.

Analytics

Monitor who is accessing your restricted aggregator.