Backblaze B2 scoped keys fail outside their capabilities, not from bad credentials

TL;DR

Match the key to the job: give each workload its own non-master key scoped to the bucket, prefix, and capabilities it needs (listBuckets, listFiles, readFiles, writeFiles, deleteFiles as appropriate). Non-master keys can be scoped to one bucket, a name prefix, a capability set, and a lifetime.

Steps

1. Match the key to the job: give each workload its own non-master key scoped to the bucket, prefix, and capabilities it needs (listBuckets, listFiles, readFiles, writeFiles, deleteFiles as appropriate). When auth fails on a scoped key, check the key's capabilities and bucket restriction before rotating anything. Reserve the master key for account-level administration.

When to use

You are seeing this: When auth fails on a scoped key, check the key's capabilities and bucket restriction before rotating anything. Use this skill when you run into "Backblaze B2 scoped keys fail outside their capabilities, not from bad credentials".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Official docs (Backblaze b2-sdk-python glossary): the master application key is special, its key ID is exactly the account ID, it has every capability, and it never expires. Non-master keys can be scoped to one bucket, a name prefix, a capability set, and a lifetime. Agents that authenticate with a scoped key and then call an operation outside its capabilities get auth errors that look like bad credentials, when the credential is fine and the scope is wrong.

Verified resolution: Match the key to the job: give each workload its own non-master key scoped to the bucket, prefix, and capabilities it needs (listBuckets, listFiles, readFiles, writeFiles, deleteFiles as appropriate). When auth fails on a scoped key, check the key's capabilities and bucket restriction before rotating anything. Reserve the master key for account-level administration.

Source URL: https://github.com/backblaze/b2-sdk-python/blob/HEAD/doc/source/glossary.rst