b2_get_download_authorization
- 11 Sep 2026
- Print
- DarkLight
b2_get_download_authorization
- Updated on 11 Sep 2026
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Post
/b2api/v4/b2_get_download_authorization
Generates an authorization token for downloading files
Used to generate an authorization token that can be used to download files with the specified prefix (and other optional headers) from a private B2 bucket. Returns an authorization token that can be passed to b2_download_file_by_name in the Authorization header or as an Authorization parameter.
NOTE:
This API endpoint can be called using a GET request by converting the parameters in the request body to query parameters.
API Versions
v1: Application keys (July 26, 2018)
Incompatible change: After calling b2_authorize_account with an application key that does not have the right permissions, this call will return a 401 Unauthorized.
v1: Original release (September 22, 2015)
For information on all API versions, view our API changelog.
Header parameters
Authorization
stringRequired
An account authorization token, obtained from b2_authorize_account.
The token must have the shareFiles capability.
Body parameters
object
bucketId
string Required
The identifier for the bucket.
Examplea71f544e781e6891531b001a
fileNamePrefix
string Required
The file name prefix of files the download authorization token will allow b2_download_file_by_name to access. For example, if you have a private bucket named "photos" and generate a download authorization token for the fileNamePrefix "pets/" you will be able to use the download authorization token to access:
https://f345.backblazeb2.com/file/photos/pets/kitten.jpg but not https://f345.backblazeb2.com/file/photos/vacation.jpg.
Examplepets/
validDurationInSeconds
integer Required
The number of seconds before the authorization token will expire. The minimum value is 1 second. The maximum value is 604800 which is one week in seconds.
Example604800
b2ContentDisposition
string
If this is present, download requests using the returned authorization must include the same value for b2ContentDisposition. The value must match the grammar specified in RFC 6266 (except that parameter names that contain an '*' are not allowed).
Example
b2ContentLanguage
string
If this is present, download requests using the returned authorization must include the same value for b2ContentLanguage. The value must match the grammar specified in RFC 2616.
Example
b2Expires
string
If this is present, download requests using the returned authorization must include the same value for b2Expires. The value must match the grammar specified in RFC 2616.
Example
b2CacheControl
string
If this is present, download requests using the returned authorization must include the same value for b2CacheControl. The value must match the grammar specified in RFC 2616.
Example
b2ContentEncoding
string
If this is present, download requests using the returned authorization must include the same value for b2ContentEncoding. The value must match the grammar specified in RFC 2616.
Example
b2ContentType
string
If this is present, download requests using the returned authorization must include the same value for b2ContentType. The value must match the grammar specified in RFC 2616.
Example
Responses
200
The request succeeded.
The response headers include the Content-Type that was specified when the file was uploaded. They also include the X-Bz-FileName and X-Bz-Content-Sha1 headers, plus X-Bz-Info-* headers for any custom file info that was provided with the upload. The X-Bz-FileName uses percent-encoding, as if it were a URL parameter.
object
bucketId
string
The identifier for the bucket.
Examplea71f544e781e6891531b001a
fileNamePrefix
string
The prefix for files the authorization token will allow b2_download_file_by_name to access.
Examplepets
authorizationToken
string
The authorization token that can be passed in the Authorization header or as an Authorization parameter to b2_download_file_by_name to access files beginning with the file name prefix.
Example3_20160803004041_53982a92f631a8c7303e3266_d940c7f5ee17cd1de3758aaacf1024188bc0cd0b_000_20160804004041_0006_dnld
400
| status | code | description |
|---|---|---|
| 400 | bad_bucket_id | The requested bucket ID does not match an existing bucket. |
| 400 | bad_request | The request had the wrong fields or illegal values. The message returned with the error will describe the problem. |
object
status
integer
The numeric HTTP status code. Always matches the status in the HTTP response.
Example400
code
string
A single-identifier code that identifies the error.
Exampleinvalid_bucket_name
message
string
A human-readable message, in English, saying what went wrong.
Examplebucket name is too long
401
| status | code | description |
|---|---|---|
| 401 | bad_auth_token | The auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem. |
| 401 | expired_auth_token | The auth token used has expired. Call b2_authorize_account again to get a new one. |
| 401 | unauthorized | The auth token used is valid, but does not authorize this call with these parameters. The capabilities of an auth token are determined by the application key used with b2_authorize_account. |
403
| status | code | description |
|---|---|---|
| 403 | transaction_cap_exceeded | Transaction cap exceeded. Daily transaction caps apply to non-paying accounts. To view or adjust your caps, sign in to your B2 Cloud Storage account online and select the Caps & Alerts link in the B2 Cloud Storage section of the sidebar. |
503
| status | code | description |
|---|---|---|
| 503 | service_unavailable | <various> |
Was this article helpful?