Secure URLs
Bytescale lets you securely share and track access to private files through Secure URLs.
Files in Bytescale can be marked as either public or private, based on your folder’s permission settings.
To access private files, you have two options:
HTTP Headers: use the Authorization or Authorization-Token header to authenticate requests.
Secure URLs: use Secure URLs (Signed URLs or Encrypted URLs) to authenticate requests via the query string.
To implement Secure URLs in your application, please see:
Benefits of Secure URLs
Compared to header-based authentication, Secure URLs offer greater flexibility by allowing access to private files without requiring control over HTTP request headers. While HTTP authentication headers work well in environments where you can manage headers, they have several limitations that Secure URLs are designed to address:
When using headers for authentication, each variation of the Authorization, Authorization-Token, and Cookie headers create a separate cache entry. These headers are typically unique to each user's session. In contrast, Secure URLs can be generated deterministically—allowing shared caching for identical files across users and sessions.
Secure URLs are ideal in environments where controlling HTTP request headers is impractical or impossible—such as email links or chat messages—allowing secure access with no extra setup.
Secure URLs allow you to construct URLs that cannot be modified, which prevents the file path and transformation parameters from being changed by your users. This is especially useful for scenarios where you need to serve dynamic watermarks or low-resolution images by default, while restricting high-resolution versions to premium customers.
Since Secure URLs are immutable, you can also add metadata parameters to your URLs to trace the source of any leaks, and limit the impact of leaks by setting short expiration parameters.
Encrypted URLs conceal all query parameters—and optionally the file path itself—hiding transformation settings, file names, and folder structure from public view.
Signed URLs provide a simpler alternative to Encrypted URLs for cases where plaintext URLs are acceptable, but URL immutability and access control for private files are still required.
Header-based authentication requires you to specify a user’s entire permission set up front, either in the API key's settings or in the JWT, which means you may hit size limits when dealing with complex or highly dynamic permission sets.
With Secure URLs, your backend determines access at the moment the URL is generated. This gives you more flexibility—for example, you can query per-file access rights from your database based on the user's current memberships, subscriptions, or other dynamic conditions.
Signed URLs vs Encrypted URLs
Signed URLs and Encrypted URLs are collectively referred to as Secure URLs — you can only use one of these methods on any given URL.
Uses the sig query string parameter to append an HMAC SHA-256 signature to the URL.
Uses the exp query string parameter to set a URL expiration time.
The URL is pre-authenticated using an API key, and inherits the API key's permissions at the time the request is served.
The URL remains in plaintext.
The URL cannot be modified without breaking the signature.
Read the docs: Signed URLs
Uses the enc query string parameter to replace the entire query string with an AES-GCM-encrypted query string.
Uses the exp query string parameter to set a URL expiration time.
The URL is pre-authenticated using an API key, and inherits the API key's permissions at the time the request is served.
The URL path remains in plaintext, but the query string is fully encrypted.
If the enc query string parameter is present, then no other query string parameters are allowed; the exp parameter is added before encryption to abide this constraint, meaning after encryption, the enc parameter will be the only parameter present on the query string.
The URL query string cannot be modified.
The URL path can be modified — but you can prevent changes to the file path (i.e. the file identifier) by using the path query parameter. This overrides any file path in the URL path itself, allowing you to move the file path into the encrypted portion of the URL, where it cannot be altered. You can also restrict access to delivery methods (e.g. /raw/, /image/, etc.) via the API key's settings, and if needed, you can use different API keys to encrypt URLs for different delivery methods.
At present, when using Encrypted URLs, bandwidth logs will not be aggregated by path. This means any such logs requested via a support ticket will be less useful for debugging bandwidth usage. Note: This behavior may change in the future, as Bytescale may switch to logging decrypted URLs to provide more meaningful bandwidth logs to its customers.
Read the docs: Encrypted URLs
Signed URLs: the right choice if you need URL-based authentication to grant access to private files or to prevent URLs from being modified by your users, but are unsure whether to use Signed URLs or Encrypted URLs. Signed URLs are slightly easier to implement, the URLs are typically shorter in length, and since the URL remains in plaintext (but is cryptographically signed), they are easier to debug and reason about within your application.
Encrypted URLs: the right choice if you need to hide file paths and/or transformation parameters from your users.