From 89e3051fa26472c6ca14c52ae7e77600f3fa000a Mon Sep 17 00:00:00 2001 From: Karl Rankla Date: Thu, 16 Jul 2026 15:45:57 +0300 Subject: [PATCH] docs(files): document custom_download_url signature verification semantics The signature now covers a canonical form of the URL (query params sorted by key), so verification is independent of query parameter order. Document that consumers should pass the request URL exactly as received, that all params must be unmodified, and the 15-minute signature TTL. --- docs/files/file-api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/files/file-api.md b/docs/files/file-api.md index 3bf9c58..bd4a935 100644 --- a/docs/files/file-api.md +++ b/docs/files/file-api.md @@ -216,6 +216,10 @@ POST /v2/files epilot retrieves external files on the fly with a short-lived signature and streams them directly to the end user. Use the [`verifyCustomDownloadUrl` operation](/api/file#tag/files/operation/verifyCustomDownloadUrl) to verify that a download request originates from epilot. +:::info Signature verification details +Pass the **full request URL exactly as received** to `verifyCustomDownloadUrl`. The signature covers a canonical form of the URL (query parameters sorted by key), so validity does not depend on the query parameter **order** — but every parameter and value must be present and unmodified. Signatures are cryptographically bound to the epilot organization and expire **15 minutes** after minting. +::: + ![External file download flow](../../static/img/file-custom-url-flow.png) :::warning