Menu

Mattering Automations Backblaze B2 integration

Connect Backblaze B2 to Mattering Automations: buckets, files and versions, uploads from a URL, copies, hides and deletes, downloads and share links, multipart large files, application keys, Object Lock and event notification rules as workflow steps, authenticated with an application key id and application key.

The Mattering Automations Backblaze B2 integration puts the B2 Native API v4 on your automation canvas: list, create, update and delete buckets, list files by name and by version, upload from a URL, copy, hide and delete versions, download small files and mint time-limited share links, run multipart uploads for large files, create and revoke application keys, set Object Lock legal holds and retention, and read and write event notification rules.

The credential is an application key id and an application key from your Backblaze account's Application Keys page. What happens with them is unusual enough to explain up front, because it is why a stored credential can look fine and still need a refresh. Those two values authenticate exactly one call: an authorization request sent as HTTP Basic to a fixed Backblaze host. That call returns an authorization token valid for at most 24 hours and the API host for the CLUSTER your account lives on, which Backblaze assigns per account and which cannot be guessed. Every other request in this integration uses that derived token against that derived host, and Mattering performs and caches the exchange for you.

One behaviour of B2 shapes almost everything you will build, so read it before the setup steps. B2 buckets are versioned by default and versioning cannot be turned off. Every upload to an existing name creates a new version, the newest is what a download by name serves, and older versions keep existing and keep being billed until something removes them. That is why Backblaze B2: Hide File and Backblaze B2: Delete File Version are genuinely different operations rather than two words for the same thing.

Before you start

  • A Backblaze account with B2 Cloud Storage enabled, and permission to create an application key on its Application Keys page.
  • A decision about the key's capabilities, because capability rather than plan is what gates the nodes here. A read-only key cannot upload; listing parts is gated on the write-files capability rather than the list-files one; listing keys and creating keys need their own capabilities, and a key able to create keys is effectively a full-account key; download authorizations need the share-files capability; and the Object Lock nodes need Object Lock enabled on the bucket plus the matching write capability.
  • If the key is restricted to a bucket, know it. On API v2 and later, asking for every bucket with a bucket-restricted key is refused rather than quietly returning the one bucket, so Backblaze B2: List Buckets needs its bucket filter filled in, and every bucket picker in the integration reads from that lister.
  • An understanding that this integration uses the NATIVE API rather than the S3-compatible one. The two surfaces have different delete semantics on the same bucket, and mixing them in one workflow is how a delete does something other than what was intended.
  • A Mattering workspace with access to the Automations app.
  • Not required and not stored here: an account id, an API host or an upload URL. All three are derived at run time from the authorization exchange, which is also why no node asks for them.

Create a Backblaze B2 application key

Backblaze issues application keys as two values, and only one of them is ever shown again. Scope the key while you create it, because the capability list, the bucket restriction and the name prefix are what decide which nodes will work, and none of them can be widened afterwards without issuing a new key.

Sign in to Backblaze and open the Application Keys page of your account.
Click Add a New Application Key, name it for where it will be used, and choose the narrowest capability set that covers the nodes you intend to run. Restrict it to a bucket and a name prefix as well if that suits the job.
Copy the application key the moment it appears. Backblaze shows the secret half exactly once at creation and it can never be retrieved again, so a lost key is replaced rather than recovered. The application key id stays visible on the page.
Capability choices have consequences that are easy to miss. Listing parts of a large file needs the write-files capability rather than the list-files one. A key holding the write-keys capability can mint any other key, so treat it as equivalent to full account access. On API v4, deleting an application key works only with a Multi-Bucket Application Key.
If you restricted the key to a bucket, note the bucket id or name as well. You will need it on Backblaze B2: List Buckets, because an unfiltered listing with a restricted key is refused.

Connect Backblaze B2 to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Backblaze B2 from the list.
Click Create new credential, put the key id into Application Key ID and the secret into Application Key, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs. Mattering exchanges these two values for a short-lived authorization token and your account's cluster host on first use and caches the result, refreshing well inside the token's 24 hour lifetime so that a key revoked in the Backblaze console stops working quickly rather than up to a day later.
Click Test Connection. Mattering runs the authorization exchange and reports what came back: the cluster host your account lives on and the key's own capability list, bucket restrictions and name prefix. Read that message rather than just the tick, because it is the answer to most later failures.
A passing connection test proves the key is valid and the account is reachable. It does not prove any individual node will work, because every other call goes to the derived cluster host with a different header shape, and a valid key can still lack a node's capability or be restricted to a different bucket. Run the verify steps below as well.
Click Connect. All 31 Backblaze B2 nodes appear in your canvas palette.

Verify it works

Open any automation canvas and check the palette for a Backblaze B2 section. Drop Backblaze B2: List Buckets onto it and run a test step. This is the probe that matters, because it is the only one that exercises the whole derived chain: the authorization exchange, then the cluster host that exchange returned, then the bare-token header every node uses. It returns each bucket with its type, CORS and lifecycle rules, default encryption and Object Lock configuration. If your key is restricted to one bucket, fill in Bucket ID or Bucket Name first, because an unfiltered listing with a restricted key is refused rather than narrowed.

Drop Backblaze B2: Get Account Info onto the canvas and run it. It reports the account id, the cluster's API, download and S3 host names, the recommended and minimum part sizes for large file uploads, and the key's own capability list, bucket restrictions and name prefix. It never returns the authorization token. Keep this node in mind rather than in a bookmark: it is the first thing to run when any other node returns unauthorized, because the usual cause is a capability or a restriction rather than a broken credential.

Finish with a read of real content. Drop Backblaze B2: List File Names onto the canvas, choose a bucket from the picker, and run it: it returns the CURRENT version of each file, in name order, with hidden files and older versions excluded, which is the view that matches what a download by name would serve. Then run Backblaze B2: List File Versions on the same bucket and compare. The second list is longer, and every entry in it is billed storage. Everything in this path is read-only, so it cannot reach any of the four destructive nodes and is safe to re-run whenever you rotate the key.

Node reference

31 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 13

Backblaze B2: Download File By ID

backblaze_download_file_by_id

Download one specific file VERSION by its id. This is how you read a version that is no longer current, including one hidden behind a hide marker, which download by name cannot reach. Same body handling as download by name: UTF-8 text as content, anything else base64, capped at 256 KB with truncated and the real size always reported.

Backblaze B2: Download File By Name

backblaze_download_file_by_name

Download the CURRENT version of a file by bucket name and file name. Text that decodes as UTF-8 comes back as content with encoding utf-8; anything else comes back base64 in the same field with encoding base64. The body is capped at 256 KB of raw bytes, and truncated plus the real size are always reported, so a clipped read is never mistaken for a whole one. For anything larger, use Backblaze B2: Get Download Authorization and hand the URL to a worker that can stream it. A hidden name answers 404 even though its earlier versions still exist; fetch those by id instead. This node goes to the account's download host, which is a different host from every other node here.

Backblaze B2: Get Account Info

backblaze_get_account_info

Report what this connection's application key actually is: the account id, the cluster's API, download and S3 host names, the recommended and minimum part sizes for large file uploads, and the key's own capability list, bucket restrictions and name prefix. Run it FIRST when a node returns unauthorized, because the usual cause is a key missing a capability or restricted to a different bucket rather than a broken credential. This node makes no API call of its own beyond the authorization every node already performs, and it NEVER returns the authorization token.

Backblaze B2: Get Bucket Notification Rules

backblaze_get_bucket_notification_rules

Read a bucket's event notification rules: which events fire a webhook, the name prefix each rule watches, the target URL and custom headers, and whether a rule has been SUSPENDED by Backblaze along with the reason. Note that this endpoint answers with a top level JSON ARRAY rather than an object, so downstream paths read data[].eventNotificationRules[]. Read this before writing rules, because setting them replaces the whole list.

Backblaze B2: Get File Info

backblaze_get_file_info

Fetch one file VERSION's metadata without downloading it: name, size, content type, SHA1, custom file info, Object Lock retention and legal hold, encryption and upload time. The cheap way to confirm a version exists, and the documented way to check whether a Backblaze B2: Finish Large File call that timed out actually succeeded before retrying it.

Backblaze B2: Get Upload Part URL

backblaze_get_upload_part_url

Mint an upload URL and token for uploading PARTS of one large file. Classed a Safe Read because it creates nothing, but what it returns is a write credential for that large file, valid for at most 24 hours or until the endpoint rejects an upload. One token cannot serve two part uploads at the same time, so request one per parallel stream. For ordinary use, Backblaze B2: Upload Part fetches its own URL and retries on a fresh one, and this node is only needed to hand the upload to an external worker.

Backblaze B2: Get Upload URL

backblaze_get_upload_url

Mint an upload URL and upload token for a bucket. Classed a Safe Read because it creates, changes and deletes nothing, but WHAT IT RETURNS IS A WRITE CREDENTIAL: whoever holds the pair can upload into that bucket without any further authentication until it expires, which Backblaze documents as at most 24 hours or until the endpoint rejects an upload. Use this only to hand an upload off to a worker that can stream a large file; for ordinary uploads use Backblaze B2: Upload File, which fetches its own URL and retries on a fresh one. One token cannot serve two uploads at the same time, so request one per parallel stream.

Backblaze B2: List Application Keys

backblaze_list_keys

List the account's application keys with each one's name, capabilities, bucket restrictions, name prefix and expiration. The secret half of a key is NEVER returned here: it is shown exactly once, when the key is created. This node populates the key picker on Backblaze B2: Delete Application Key. Requires the listKeys capability, which most restricted keys do not have.

Backblaze B2: List Buckets

backblaze_list_buckets

List the account's B2 buckets with each one's type, CORS and lifecycle rules, default encryption and Object Lock configuration. This is the node every bucket picker in this connector reads from, and the cheapest call for confirming the credential works end to end. Note that this is the one listing endpoint B2 documents as a POST. IF YOUR APPLICATION KEY IS RESTRICTED TO A BUCKET you must fill in bucketId or bucketName: asking for all buckets with a restricted key is unauthorized.

Backblaze B2: List File Names

backblaze_list_file_names

List the CURRENT version of each file in a bucket, in name order. Hidden files are not listed and neither are older versions, so this is the view that matches what a download-by-name would serve. Use Backblaze B2: List File Versions instead when you need hide markers or history. This node populates the file name picker on the hide node. A prefix-restricted application key must pass a prefix at least as restrictive as its own or the listing is denied.

Backblaze B2: List File Versions

backblaze_list_file_versions

List EVERY version of every file in a bucket, ordered by name and then newest first within a name. This is the only view that shows history and hide markers: a version with action "hide" and contentType application/x-bz-hide-marker is a hide marker, not a file. It is also where the fileId for Backblaze B2: Delete File Version comes from. Every version listed here is BILLED STORAGE, so this is the node that finds what a bucket is actually costing. Backblaze warns that accumulating millions of versions of one name degrades listing and deletion, raises 503 rates, and can eventually block the account from uploading.

Backblaze B2: List Parts

backblaze_list_parts

List the parts already uploaded for one unfinished large file, with each part's number, size and SHA1. This is how you rebuild the partSha1Array that Backblaze B2: Finish Large File needs after a workflow was interrupted, and how you find which part number to resume from. Note that B2 gates this endpoint on the writeFiles capability rather than listFiles, which is easy to miss when scoping a read only key.

Backblaze B2: List Unfinished Large Files

backblaze_list_unfinished_large_files

List large file uploads that were started and never finished. Their parts are stored and BILLED even though no file is visible in the bucket, so this is the node that finds silent storage cost. Clear them with Backblaze B2: Cancel Large File, or automatically with a lifecycle rule using daysFromStartingToCancelingUnfinishedLargeFiles.

Action nodes 18

Backblaze B2: Cancel Large File

backblaze_cancel_large_file

DESTRUCTIVE: cancel an unfinished large file and discard EVERY PART already uploaded to it. Those bytes are gone and cannot be recovered, and the upload has to start again from Backblaze B2: Start Large File. What is NOT affected is the bucket's existing contents: an unfinished large file was never a visible file, so no version of anything is lost and nothing that was previously downloadable stops being downloadable. This is the right node for clearing the billable parts that Backblaze B2: List Unfinished Large Files reports.

Backblaze B2: Copy File

backblaze_copy_file

Copy a file version inside B2 without moving the bytes through this automation. The destination may be a different bucket in the same account; leave destinationBucketId blank to copy within the source's own bucket. The source is left untouched, so a move is this node followed by Backblaze B2: Hide File or Delete File Version. Copying onto an existing name creates a NEW VERSION of that name rather than replacing it. Files larger than 5 GB must be copied with Backblaze B2: Copy Part instead.

Backblaze B2: Copy Part

backblaze_copy_part

Copy a byte range of an existing file straight into a part of a large file, without the bytes passing through this automation. This is how a file above 5 GB is copied, and how a new file is assembled from pieces of existing ones. Same numbering rules as Backblaze B2: Upload Part: 1 to 10000, contiguous, starting at 1.

Backblaze B2: Create Application Key

backblaze_create_key

Create an application key scoped to a capability list, optionally restricted to specific buckets and a name prefix. THE SECRET IS RETURNED ONCE, in this response's applicationKey field, and can never be retrieved again, so capture it in the same run or the key is useless. Grant the narrowest capability set that works: a key holding writeKeys can mint any other key and is therefore equivalent to full account access. Reversible with Backblaze B2: Delete Application Key. Requires the writeKeys capability.

Backblaze B2: Create Bucket

backblaze_create_bucket

Create a B2 bucket. Bucket names are GLOBALLY unique across all of Backblaze, not just your account, so a create fails if the name is taken anywhere. Reversible with Backblaze B2: Delete Bucket while the bucket still holds no version of any file. Setting bucketType to allPublic makes every file in it readable by anyone with the URL and no authentication. Turning fileLockEnabled on cannot be undone.

Backblaze B2: Delete Application Key

backblaze_delete_key

DESTRUCTIVE: permanently revoke an application key. Every integration authenticating with it starts failing immediately, and the key CANNOT be restored: its secret half was shown only once at creation, so recreating it means issuing a new key and updating everything that used the old one. What is NOT affected is data: no bucket, file or version is touched. Check what the key is used for with Backblaze B2: List Application Keys first. Note that on API v4 this only works with a Multi-Bucket Application Key.

Backblaze B2: Delete Bucket

backblaze_delete_bucket

DESTRUCTIVE: delete a B2 bucket. The bucket must contain NO VERSION OF ANY FILE, including hide markers and unfinished large files, so the call fails rather than destroying data you forgot about. What IS lost and not recoverable is the bucket's configuration (CORS rules, lifecycle rules, notification rules, encryption and Object Lock settings) and its name, which is globally unique and may be taken by somebody else once released.

Backblaze B2: Delete File Version

backblaze_delete_file_version

DESTRUCTIVE: permanently delete ONE VERSION of a file. Backblaze describes this as deleting the version and all of its data as if it had never been uploaded, and nothing restores it. Read the scope carefully in both directions. It deletes only the version you name, so if older versions exist the next most recent SILENTLY becomes the one served by name and the delete can look like it did nothing; run it over every version from Backblaze B2: List File Versions to remove a file completely. If it was the only version, the file is gone entirely. Deleting a hide marker UNHIDES the name. Pointed at an unfinished large file this behaves like cancelling that upload. Use Backblaze B2: Hide File instead when you want a recoverable soft delete.

Backblaze B2: Finish Large File

backblaze_finish_large_file

Assemble the uploaded parts into a single file, which is the moment it becomes visible in the bucket. partSha1Array must list every part's SHA1 IN PART ORDER starting at part 1, and B2 rejects the call if the set is incomplete or the digests do not match. The finished file's contentSha1 comes back as the literal "none", which is normal for large files. ONE RETRY TRAP worth knowing: if this call times out after it actually succeeded, retrying returns HTTP 400, so check with Backblaze B2: Get File Info before assuming it failed.

Backblaze B2: Get Download Authorization

backblaze_get_download_authorization

Mint a time limited token that lets anyone holding it download files under a name prefix in a private bucket, with no further authentication. Append it to a download URL as the Authorization header or as an ?Authorization= query parameter. THE TOKEN GRANTS REAL READ ACCESS to everything matching the prefix for its whole lifetime and CANNOT BE REVOKED EARLY, so keep validDurationInSeconds short, make the prefix as narrow as possible, and keep the value out of anywhere URLs get logged or forwarded casually. Nothing is created that needs cleaning up: the token expires on its own. Requires the shareFiles capability.

Backblaze B2: Hide File

backblaze_hide_file

Hide a file name so it stops being served. THIS IS NOT A DELETE, and the difference matters twice over. What it actually does is write a new VERSION that is a hide marker, after which the name returns 404 on download and disappears from Backblaze B2: List File Names. Every earlier version still exists, is still reachable by fileId, still appears in Backblaze B2: List File Versions, AND IS STILL BILLED, so hiding reclaims no storage. It is reversible two ways: upload a new version of the name, or delete the hide marker itself with Backblaze B2: Delete File Version, since the marker is a version with its own fileId. If you meant to free the storage, delete the versions instead.

Backblaze B2: Set Bucket Notification Rules

backblaze_set_bucket_notification_rules

REPLACE a bucket's event notification rules with the list you supply. This is a whole-list write, not a merge: any rule you leave out is removed and its webhook stops firing immediately, so read the current set with Backblaze B2: Get Bucket Notification Rules first and write the edited list back. Passing an empty array removes every rule. The response, like the read, is a top level JSON array. Note that outbound notifications are the one part of this API that Backblaze bills as Class D transactions.

Backblaze B2: Start Large File

backblaze_start_large_file

Begin a multipart upload and return the large file's id, which every later step needs. Nothing is visible in the bucket until Backblaze B2: Finish Large File succeeds, but the parts you upload ARE STORED AND BILLED from the moment they land, so an abandoned large file costs money indefinitely. Clean up with Backblaze B2: List Unfinished Large Files and Cancel Large File, or set a lifecycle rule with daysFromStartingToCancelingUnfinishedLargeFiles on the bucket. Reversible with Cancel Large File.

Backblaze B2: Update Bucket

backblaze_update_bucket

Update a bucket's settings. Only the fields you fill in are sent, but each one you DO send REPLACES that setting wholesale rather than merging: sending corsRules or lifecycleRules drops any rule you left out, so read the current set with Backblaze B2: List Buckets first and write the edited list back. Set ifRevisionIs to the bucket's current revision to make the update fail rather than clobber a concurrent change. Switching bucketType to allPublic makes every file in the bucket world readable.

Backblaze B2: Update File Legal Hold

backblaze_update_file_legal_hold

Turn an Object Lock legal hold on or off for one file version. While a hold is ON the version cannot be deleted or overwritten by anyone, including the account owner, and it has no expiry: it stays until someone turns it off. That is what makes this reversible in both directions and worth reaching for over a retention period when the end date is unknown. Requires Object Lock enabled on the bucket and the writeFileLegalHolds capability.

Backblaze B2: Update File Retention

backblaze_update_file_retention

Set or change an Object Lock retention on one file version. READ THE TWO MODES BEFORE USING THIS. GOVERNANCE retention blocks deletion until the timestamp passes, but a key holding the bypassGovernance capability can shorten or remove it, which is why this node is reversible. COMPLIANCE retention CANNOT BE SHORTENED OR REMOVED BY ANYONE, including the account owner and Backblaze support, until it expires, so a compliance retention set far in the future makes that version undeletable and its storage unavoidably billable for the whole period. Requires Object Lock enabled on the bucket and the writeFileRetentions capability.

Backblaze B2: Upload File

backblaze_upload_file

Upload a file. This node does BOTH halves of B2's upload flow: it fetches a fresh upload URL for the bucket, uploads the bytes with the SHA1 checksum B2 requires, and on a 401, 408, 429 or 5xx it fetches a NEW upload URL and retries once, which is Backblaze's own documented advice. Give it content_url and the runner downloads that URL and stores the bytes, which is the right shape for real files; give it content for small inline text. One or the other, never both. UPLOADING TO A NAME THAT ALREADY EXISTS DOES NOT REPLACE ANYTHING: B2 buckets are versioned and the old version stays, still stored and still billed, until something hides or deletes it. Files above the node's 100 MB cap should use the large file nodes.

Backblaze B2: Upload Part

backblaze_upload_part

Upload one part of a large file. Like Backblaze B2: Upload File, this node does both halves: it fetches a fresh part upload URL, uploads the bytes with their SHA1, and retries once on a new URL after a 401, 408, 429 or 5xx. Part numbers run from 1 to 10000 and MUST BE CONTIGUOUS STARTING AT 1, or Backblaze B2: Finish Large File rejects the set. Every part except the last must be at least the account's minimum part size, which Backblaze B2: Get Account Info reports as absoluteMinimumPartSize. Keep each part's SHA1 from this node's output: finishing the file needs all of them in order.

Using the integration

On the automation canvas

Backblaze B2 nodes chain with every other node. A worker's output can be archived with Backblaze B2: Upload File straight from a URL, a nightly schedule can inventory versions and open a task when storage climbs, and Backblaze B2: Get Download Authorization can produce a share link that a Comms message or an email step delivers. Bucket fields are pickers sourced from Backblaze B2: List Buckets, labelled by bucket name because a B2 bucket id is 24 opaque characters, and described by bucket type so you can see when you are about to write into a public bucket. File name fields on the hide node are picked from Backblaze B2: List File Names, scoped to the bucket chosen on the same form.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. The comfortable surface for an agent is the read side plus uploads: Backblaze B2: List Buckets, Backblaze B2: List File Names, Backblaze B2: List File Versions, Backblaze B2: Get File Info and Backblaze B2: Upload File. Keep the four destructive nodes behind a condition or an approval task, and treat Backblaze B2: Get Download Authorization and Backblaze B2: Create Application Key as sensitive rather than routine, because both return credentials that grant real access. Running the nodes here rather than as a local tool also means they work on a schedule with nobody present, chain with every other connector in one workflow, and hold the application key in the workspace credential store rather than in one person's client config.

How the two-step authorization works, and why it matters

The application key id and application key you paste authenticate exactly one call: an authorization request sent as HTTP Basic to a fixed Backblaze host. That call returns an authorization token valid for at most 24 hours, the API host for the CLUSTER your account lives on, the download host, your account id, your key's allowed capabilities and the recommended part sizes. Everything else in this integration goes to those derived hosts with the derived token, which is a bare value rather than a Basic or Bearer header. Mattering performs the exchange, caches the bundle, and refreshes it well inside the token's lifetime on purpose, so a key revoked in the Backblaze console stops working within the hour rather than within the day. If a token expires mid workflow, the connector re-authorizes once and replays the request, re-reading the HOST from the fresh authorization rather than only the token, and it retries once rather than in a loop so a genuinely bad key surfaces as an error. Two consequences you get for free: no node ever asks for an API host, and no node asks for your account id, because the authorization already carried it.

Versioning, and why hiding is not deleting

B2 buckets are versioned by default and versioning cannot be turned off, which is the fact underneath every file operation here. Backblaze B2: Hide File writes a new version that is a hide marker: the name then returns 404 on download and disappears from Backblaze B2: List File Names, while every earlier version still exists, is still reachable by file id, still appears in Backblaze B2: List File Versions, and is STILL BILLED. Hiding reclaims no storage. It is reversible two ways: upload a new version of the name, or delete the hide marker itself, since the marker is a version with its own file id. Backblaze B2: Delete File Version is the real delete, of ONE version, described by Backblaze as removing the version and all of its data as if it had never been uploaded. Read its scope in both directions: if older versions exist the next most recent silently becomes the one served by name, so the delete can look like it did nothing, and removing a file completely means running it over every version. If it was the only version, the file is gone entirely. Deleting a hide marker unhides the name, which is a delete that restores data.

Uploading, and what an upload does not do

Backblaze B2: Upload File does both halves of B2's upload flow in one node: it fetches a fresh upload URL for the bucket, uploads the bytes with the checksum B2 requires, and on certain failures fetches a NEW upload URL and retries once, which is Backblaze's own documented advice and something a static graph cannot express by hand. Give it a content URL and the runner downloads and stores that, which is the right shape for real files; inline content is for small text. Uploads through this node are capped at 100 MB, which is also Backblaze's recommended part size. The thing to internalise: uploading to a name that already exists does NOT replace anything, because the bucket is versioned, so the old version stays, stored and billed, until something hides or deletes it. Backblaze B2: Get Upload URL still exists as its own node for handing an upload to an external worker, and its output is a write credential for that bucket rather than a harmless address.

Large files, and resuming one that was interrupted

Above the upload node's cap, the large file family takes over: Backblaze B2: Start Large File returns the id every later step needs, Backblaze B2: Upload Part composes fetching a part upload URL with the upload and retries once on a fresh URL, and Backblaze B2: Finish Large File assembles the parts. Part numbers run from 1 upwards, must be contiguous and must start at 1, and finishing needs every part's checksum in order, so keep them from each part node's output. Two operational notes save real time. If a workflow was interrupted, Backblaze B2: List Parts rebuilds what is already uploaded and tells you where to resume, and it is gated on the write-files capability rather than the list-files one. And if the finish call times out after it actually succeeded, retrying returns an error, so check with Backblaze B2: Get File Info before assuming failure. Parts of an unfinished large file are stored and billed while being invisible in the bucket, which is what Backblaze B2: List Unfinished Large Files and Backblaze B2: Cancel Large File are for.

Downloads and share links

Backblaze B2: Download File By Name fetches the current version and Backblaze B2: Download File By ID fetches a specific one, including a version hidden behind a hide marker, which download by name cannot reach. Both cap the body at 256 KB of raw bytes, return text that decodes as UTF-8 as content and anything else as base64 in the same field, and always report the true size and whether the read was truncated, so a clipped read is never mistaken for a whole one. For anything larger, mint a link instead: Backblaze B2: Get Download Authorization returns a time-limited token that lets whoever holds it download files under a name prefix in a private bucket. Treat that token as the access grant it is. It cannot be revoked early, so keep the duration short, make the prefix as narrow as the job allows, and keep the value out of anywhere URLs get logged or forwarded.

Object Lock, lifecycle rules and the writes that delete later

Two reversible-looking settings schedule irreversible outcomes. Lifecycle rules on Backblaze B2: Create Bucket and Backblaze B2: Update Bucket can auto-hide files after a number of days, auto-HARD-DELETE hidden files after another, and auto-cancel stalled large files. They run once a day, and a wrong prefix expires the wrong files days later and quietly. Writing them REPLACES the current set rather than merging, so read the bucket first and write the edited list back, and note the same is true of CORS rules and of Backblaze B2: Set Bucket Notification Rules. Object Lock runs the other way: Backblaze B2: Update File Legal Hold is reversible in both directions and has no expiry, which makes it the better tool when the end date is unknown, while Backblaze B2: Update File Retention has two modes that are not alike. Governance retention can be shortened or removed by a key holding the bypass capability. Compliance retention cannot be shortened or removed by anyone, including the account owner, until it expires, so a compliance date set far in the future makes that version undeletable and its storage unavoidably billable for the whole period. Object Lock also overrides lifecycle deletion, so a rule can silently fail to reclaim space on locked files.

The four destructive nodes, gated

Backblaze B2: Delete File Version is the one that loses data, permanently and per version, with the promotion trap described above. Backblaze B2: Delete Bucket refuses unless the bucket holds no version of any file, including hide markers and unfinished large files, so it fails rather than destroying something forgotten; what it does lose for good is the bucket's configuration and its name, which is globally unique across all of Backblaze and may be claimed by someone else once released. Backblaze B2: Cancel Large File discards every part uploaded to an unfinished large file and nothing else, since such a file was never visible in the bucket, so the scariest-sounding node here is the smallest risk. Backblaze B2: Delete Application Key touches no data and is irreversible for a different reason: the secret half was shown once at creation, so the key can only be replaced, and everything authenticating with it fails immediately. Check what a key is used for with Backblaze B2: List Application Keys first.

Troubleshooting

Test Connection fails with a 401
The application key id and application key pair was rejected at the authorization step, which is the only call those two values authenticate. Check for whitespace from the copy on both halves, and remember that the secret half is shown exactly once at creation, so a value reconstructed from memory or from a partial paste cannot be corrected: create a new key on the Application Keys page and update the credential. Backblaze returns a structured error body here with its own code, and the connector passes it through rather than swallowing it, so the run record names the reason.
Test Connection passes but a node returns unauthorized
Expected often enough to be the first thing to check rather than a surprise. The connection test exercises the fixed authorization host with a Basic header, while every other node goes to your account's derived cluster host with a bare token, so a passing test proves the credential and not the node. Run Backblaze B2: Get Account Info, which reports the key's capability list, bucket restrictions and name prefix. The usual causes: the key lacks that node's capability, it is restricted to a different bucket, it is restricted to a name prefix and the node passed a broader one, or, on API v4, Backblaze B2: Delete Application Key was called without a Multi-Bucket Application Key. The one people miss most often is that Backblaze B2: List Parts is gated on the write-files capability rather than the list-files one.
List Buckets is refused, and every bucket picker is empty
The key is restricted to a bucket. On API v2 and later, asking for all buckets with a bucket-restricted key is unauthorized rather than quietly narrowed to the one bucket, which is a change from the original behaviour. Fill in Bucket ID or Bucket Name on Backblaze B2: List Buckets. Because that node is also the source for every bucket picker in the integration, a restricted key produces empty pickers everywhere until the filter is set, which reads like a broken connector and is not one.
A file was deleted but the name still downloads
You deleted one version of a versioned file. B2 buckets are versioned by default and versioning cannot be turned off, so if older versions of that name exist, deleting the current one silently promotes the next most recent to being the version served by name. Run Backblaze B2: List File Versions on the name to see the full history, and delete each version you intend to remove. If instead you wanted the name to stop being served while keeping the history, Backblaze B2: Hide File is the node for that, and it is reversible.
Hiding files did not reduce the bill
Hiding never does, and this is the expensive misunderstanding worth stating plainly. Backblaze B2: Hide File writes a hide marker version: the name stops being served and disappears from Backblaze B2: List File Names, while every earlier version still exists, is still reachable by file id and is still billed. To reclaim storage you have to delete versions with Backblaze B2: Delete File Version, or set a lifecycle rule on the bucket that hard-deletes hidden files after a number of days. Run Backblaze B2: List File Versions to see what is actually being stored, and Backblaze B2: List Unfinished Large Files for the other quiet cost, since parts uploaded to a large file that never finished are billed while invisible in the bucket.
Finish Large File returned an error on a retry
Check before retrying rather than after. Backblaze documents that finishing a large file returns an error if the call already succeeded, so a finish that timed out on the network and actually landed will report as a failure when retried, and a workflow that treats that as fatal reports a successful upload as broken. Call Backblaze B2: Get File Info with the file id first: if the file exists, the finish succeeded. If it genuinely did not, Backblaze B2: List Parts tells you what is already uploaded so the run can resume rather than restart.
Parallel uploads fail with an upload token error
One upload token cannot serve two uploads at the same time, and B2 answers the second with an error rather than queueing it. Request one upload URL per parallel stream: Backblaze B2: Upload File and Backblaze B2: Upload Part each fetch their own, so the problem usually appears when Backblaze B2: Get Upload URL output is reused across branches. The related vendor rule is worth encoding in any custom retry: on an upload failure you fetch a NEW upload URL rather than backing off against the old one, which the upload nodes already do once for you. Both URLs are valid for at most 24 hours or until the endpoint rejects an upload.
Creating a bucket fails on a name nobody in my account uses
Bucket names are globally unique across all of Backblaze rather than per account, so a name can be taken by a completely unrelated customer. Choose another. The same fact has a tail worth knowing on the way out: deleting a bucket releases its name for anyone to claim, so a teardown and rebuild workflow cannot assume the name will still be available, and Backblaze B2: Delete Bucket loses the name along with the bucket's configuration.
A template reading notification rules resolves to nothing
Those two endpoints have a different response shape from everything else in this API. Backblaze B2: Get Bucket Notification Rules and Backblaze B2: Set Bucket Notification Rules answer with a TOP-LEVEL JSON array rather than an object, so paths read data[].eventNotificationRules[] rather than data.eventNotificationRules[]. While you are there, two more shape notes: setting rules is a whole-list write, so any rule left out is removed and its webhook stops firing immediately, and Backblaze may SUSPEND a rule of its own accord, which the read node reports along with the reason. Numeric fields elsewhere in this API come back as both strings and numbers across Backblaze's own documented examples, so coerce rather than assume.
A retention setting cannot be removed
Check which mode it is, because one of them genuinely cannot be undone. Governance retention blocks deletion until its timestamp passes but can be shortened or removed by a key holding the bypass-governance capability, so the fix there is a key with the right capability. COMPLIANCE retention cannot be shortened or removed by anyone, including the account owner, until it expires, which means the version stays undeletable and its storage stays billable for the whole period. There is no support path around it. When the end date is unknown, Backblaze B2: Update File Legal Hold is the better tool, because it has no expiry and is reversible in both directions. Note as well that Object Lock overrides lifecycle deletion, so a lifecycle rule will silently fail to reclaim space on locked files.
Requests are being throttled or returning server errors
Backblaze documents a 429 with a retry-after header, and 503 responses with or without one, and its guidance differs by endpoint in a way worth encoding. On ordinary calls, honour the retry-after header, and back off exponentially from one second on a 503 that carries none. On the two UPLOAD endpoints specifically, do not back off against the same URL: fetch a NEW upload URL instead, which the upload nodes already do once for you. Two more documented conditions are worth branching on rather than retrying, because retrying will not help: a storage cap exceeded error and a transaction cap exceeded error are account limits rather than transient failures.

Backblaze B2 is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products