Cloudinary

Connecting a Cloudinary account

Authentication uses your Cloudinary cloud name, API key, and API secret (from the Cloudinary Console) — never OAuth and never the `cloudinary` npm SDK; every call is a signed, server-side `fetch` request.

R2 remains the private source of truth for every original and derivative image at all times. Cloudinary is an optional, additional remote destination — nothing is ever removed from or made dependent on R2.

The API secret is encrypted at rest and is never returned by any API response or shown again in the dashboard after it is saved — not even right after you save it.

New connections start pending and must pass a verification check (a valid cloud name, API key, and API secret confirmed against Cloudinary's ping endpoint) before they can publish.

Public vs signed delivery

`upload` (public) delivery serves images from a predictable, unsigned URL under `res.cloudinary.com` — anyone with the link can view the image. This requires an explicit, one-time acknowledgement per connection before it can be used.

`signed` delivery generates a fresh, server-computed signed URL for every request instead of trusting a stored signature, and does not require the public-delivery acknowledgement.

Choosing `upload` delivery does not change anything about R2: your private originals in R2 are unaffected and remain inaccessible to the public regardless of what you publish to Cloudinary.

What publishing does

Publishing uploads the image's active derivative (or the original, if no derivative is selected) to Cloudinary under a server-generated public ID and sets its alt text, caption, title, and description from your approved metadata as Cloudinary context metadata.

Every publish is verified by re-reading the asset back from Cloudinary's Admin API after upload; partial failures (e.g. the upload succeeded but the metadata update failed) are reported separately from full failures.

Assets are always uploaded with `overwrite=false` — an existing asset is never silently replaced — and are never re-uploaded once a remote asset id exists; retries resume from the metadata update/verification step.

Only a fixed set of transformation presets (original, thumbnail, small, medium, large) can be requested for delivery — arbitrary or user-supplied transformation strings are never accepted.

What publishing does not do

Img Pilot never calls Cloudinary's destroy/delete APIs — nothing is ever deleted remotely on Cloudinary by this integration, whether you disconnect a connection or delete the SaaS project.

Disconnecting a connection only stops future publishing and destroys the locally stored credentials; assets already published to Cloudinary remain there untouched.

The browser never talks to Cloudinary directly — every upload, verification, metadata update, and signed delivery URL is generated by our servers.

Limits and retries

Connection counts, monthly publish volume, and bulk publish batch size are limited by plan.

Failures such as authentication or permission errors are not retried automatically; rate limits and transient network or availability errors are retried with a bounded attempt count before a job is marked failed.