Downloading an authenticated result without handing out the company key

A finished processing job and a delivered file are two different events. In Skavio Agent Tools, the download step is easy to get wrong — not because the job broke, but because the API key ends up in the browser, in a chat message or in a log line. This guide describes the safer pattern: your backend holds the company-scoped credential, retrieves the artifact on the server, and only then gives an authorized person access to it.

The company key is a server credential, not a download link

Skavio Agent Tools is a company-scoped authenticated API for document, invoice, audio and data processing, with self-service keys, asynchronous jobs and a shared prepaid credit wallet. The word that matters here is company-scoped: a key represents the company, not an individual person. That is convenient for operations, because team invitations allow several people to work under the same company account and wallet, but it also defines the blast radius if the credential leaks. Anyone holding it can act as the company within the API's scope. The tempting shortcut is to let the frontend call the API directly, because then the browser can fetch the result file itself and the backend never has to stream anything. That shortcut places a company credential in client-side JavaScript, where it can be read from local storage, captured in screenshots, copied out of a developer console or replayed from a cached page. The correct shape is unglamorous: the browser talks to your application using your own session mechanism, and your application's server talks to Skavio Agent Tools using the company key.

Accepted, queued, processing and completed are four different states

Async processing means the request that creates work is not the request that returns the file. A submission can be accepted without the result existing yet, and an accepted submission is not evidence that a downloadable artifact is waiting. Build your UI around that distinction rather than around an optimistic spinner that assumes success. Agent Tools supports idempotent job submissions, which is useful precisely for the awkward moment when a client or network times out. In that moment you do not know whether the job was created. The safe move is to look up the existing job state before submitting the same work again, rather than firing a second identical request and reconciling the duplicate later. Published planning limits are worth knowing before you design the polling and download layer: 120 requests per minute, up to 100 upload files and 500 MB total per upload, 2 GB of company source storage, 100 queued company jobs, 4 active jobs, and a 7-day result retention window.

Authorize the human first, then fetch the artifact

Company-isolated jobs keep one company's work away from another's, but isolation between companies is not the same as permission inside yours. A company-scoped key is not a substitute for deciding which of your users may see which result. The sequence should be explicit and boring: verify the person's session with your own authentication, check that the requested job identifier belongs to that person's permitted scope, then have the server retrieve the artifact and stream or proxy it back. Two details are worth deciding early. First, whether you proxy the bytes through your application or redirect the user to a download location under your own control with a defined lifetime — the choice affects audit logging, bandwidth and how much control you retain after the handoff. Second, whether any result should be downloadable by an entire team or only by the person who submitted the job. Skavio documents the exact endpoint paths, authentication header format and result-download mechanics in its published documentation; follow that rather than inferring behavior from this workflow description.

Where keys actually leak: logs, tickets and screenshots

The easiest way for a credential to leak is mundane. A request dump includes the authentication header. An error payload echoes the full request object into an exception tracker. A support message pastes a curl command with the key still in it. A screenshot of a terminal or configuration screen shows the key while someone asks for help. None of these require an attacker to break anything; they only require someone helpful. Log job identifiers, status codes, timestamps and your own request identifiers. Do not log the key, and be cautious about logging full request headers by default. When you escalate a problem, redact the credential before it leaves your environment, and if you are unsure whether it was exposed, treat it as compromised and follow your key-management process. The same rule applies to the artifact itself: a result file may contain supplier invoices, customer documents or recorded audio, so treat downloaded files as sensitive data with a defined retention policy on your side too.

What to confirm in the documentation before you ship

This guide deliberately stops at the architectural boundary. It does not reproduce endpoint paths or the authentication header format, and it does not assume whether the documented download mechanism uses signed URLs, single-use links, expiry windows, checksums or byte-range streaming. Those details belong to the current Agent Tools and Processing API documentation, and they should be read at implementation time rather than assumed from a blog post. There is also a simple test that catches most design mistakes: run a job with fictional documents, then attempt the download while pretending to be a different user, and again with the browser's network tab open to confirm that no company credential ever appears in client-side traffic. If the key shows up in the browser at any point, the architecture is wrong regardless of how well the download works.

Review the Agent Tools documentation →