Present a Branded S3 Endpoint

Backblaze B2 Cloud Storage uses regional S3-Compatible API endpoints in the format s3.<region>.backblazeb2.com. Eligible Powered By Backblaze partners can use Backblaze Custom Domains to present an approved domain in place of the standard Backblaze hostname. Backblaze provides the required DNS records and requests a TLS certificate for the custom domain.

For download-focused services, you can place a CDN in front of B2. If your platform must authenticate tenants, enforce additional policies, or translate credentials, use an API gateway that creates a new Signature Version 4 request to the B2 endpoint. A generic DNS alias or ordinary reverse proxy is not sufficient for authenticated S3 requests because the HTTP Host header is part of the SigV4 signature.

This guide explains how to choose and configure the endpoint pattern. For programmatic tenant provisioning and billing, see the Powered By Backblaze Quickstart Guide and the Partner API guides.

Prerequisites

Before you begin, ensure that you have the following items:

• A Backblaze account with Backblaze B2 enabled

• A private Backblaze B2 bucket and its S3 endpoint

• An Application Key with the capabilities required by your service

• A domain that your organization controls

• Access to manage the domain's DNS records

• A decision about whether tenants need the full S3-Compatible API or only branded object delivery

• A defined credential model for each tenant

• For Backblaze Custom Domains, an eligible Powered By Backblaze deployment approved by Backblaze Sales

• For a self-managed gateway, an HTTPS certificate, secure credential storage, request logging, monitoring, and capacity for streamed uploads and downloads

Understand the Backblaze B2 S3 Endpoint Structure

The standard Backblaze B2 S3-Compatible API endpoint has the following format:

https://s3.<region>.backblazeb2.com

For example:

https://s3.us-west-004.backblazeb2.com

Backblaze supports both path-style and virtual-hosted-style addressing.

For maximum compatibility, use bucket names that contain lowercase letters, numbers, and hyphens. A bucket name that contains a period cannot use virtual-hosted-style addressing over HTTPS because a wildcard TLS certificate does not cover the additional hostname labels. Use path-style addressing for those buckets.

Endpoint Patterns

Choose an endpoint pattern based on how clients authenticate, who manages TLS, whether content should be cached, and how much control your platform requires.

Use Backblaze Custom Domains for the Full S3-Compatible API

Backblaze Custom Domains are part of the Powered By Backblaze program. You can attach a custom domain to a new or existing Backblaze Group whose members are in the same region. Backblaze evaluates requests for eligibility, charges a one-time setup fee for each approved custom domain, and coordinates the installation through the Backblaze Sales and Solutions teams.

1. Contact Backblaze Sales and request an eligibility review for Custom Domains.

2. Identify the target Group, region, approved domain, and technical point of contact.

3. Install the CNAME and ACME challenge records supplied by Backblaze.

4. Allow Backblaze to verify the DNS records and request the TLS certificate.

5. Wait for the Backblaze Solutions team to confirm that installation is complete.

6. Configure a test client with the branded endpoint and the correct B2 region.

7. Test path-style and, if required, virtual-hosted-style requests.

8. Validate uploads, multipart transfers, downloads, listings, deletes, presigned URLs, and error responses before onboarding tenants.

The exact DNS values come from Backblaze. The following example illustrates the record structure for an approved domain in us-west-004:

s3.us-west-004              CNAME  s3.us-west-004.backblazeb2.com
*.s3.us-west-004            CNAME  s3.us-west-004.backblazeb2.com
_acme-challenge.s3.us-west-004  CNAME  <validation-target-provided-by-backblaze>

If the approved domain is example.com, the resulting path-style endpoint would follow this pattern:

https://s3.us-west-004.example.com

A virtual-hosted-style request would follow this pattern:

https://<bucket-name>.s3.us-west-004.example.com/<object-key>

Use the exact hostname and region confirmed by Backblaze. Do not create your own variation of the endpoint pattern.

Configure an S3 Client with the Branded Endpoint

After Backblaze confirms the Custom Domain installation, configure S3-compatible tools and SDKs to use the branded endpoint instead of the standard backblazeb2.com endpoint.

The following Python example configures Boto3 for path-style addressing:

import os

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.us-west-004.example.com",
    region_name="us-west-004",
    aws_access_key_id=os.environ["B2_APPLICATION_KEY_ID"],
    aws_secret_access_key=os.environ["B2_APPLICATION_KEY"],
    config=Config(
        signature_version="s3v4",
        s3={"addressing_style": "path"},
    ),
)

response = s3.list_objects_v2(
    Bucket="example-bucket",
    MaxKeys=10,
)

for item in response.get("Contents", []):
    print(item["Key"])

Replace the endpoint, region, and bucket name with your values. Store application keys in a secrets-management system and inject them at runtime.

Preserve SigV4 Authentication

The B2 S3-Compatible API supports Signature Version 4. SigV4 creates a signature from a canonical representation of the request. The HTTP Host header is a required signed header, and the request path, query parameters, selected headers, payload hash, date, region, and credentials can also affect the signature.

Use the following rules to prevent signature mismatch errors:

• Configure the SDK to sign requests for the final branded hostname that the client uses.

• Use the B2 region that appears in the endpoint.

• Keep the addressing style consistent between signing and delivery.

• Do not change the Host header after the client signs the request.

• Do not decode, normalize, or rewrite the object path after signing.

• Preserve the query string, signed headers, payload hash, and request body.

• Ensure that proxies support streamed and multipart request bodies without transforming them.

• Generate presigned URLs with the final hostname that recipients will use.

An official Backblaze Custom Domain is designed to route the branded endpoint to B2. With a self-managed proxy, changing the incoming branded Host header to the standard B2 hostname invalidates an existing SigV4 signature. Either preserve a fully supported signed request path or create a new signature at the gateway.

Re-sign Requests at an API Gateway

Use a re-signing gateway when your platform must present its own authentication model rather than distributing B2 application keys directly to tenants.

1. The client sends a request to your branded endpoint and authenticates with your platform.

2. The gateway validates the tenant identity and authorizes the requested bucket, object, and operation.

3. The gateway maps the tenant to a restricted B2 application key.

4. The gateway creates a new upstream request for the tenant's B2 regional endpoint.

5. The gateway signs the new request with SigV4 and the selected B2 application key.

6. The gateway streams the request and response without loading large objects into memory.

7. The gateway records the tenant, operation, object, status, B2 request ID, timing, and bytes transferred.

Do not forward the tenant's incoming SigV4 Authorization header after changing the hostname or request. Authenticate the incoming request, remove its authorization material, and sign the new upstream request independently.

A re-signing gateway becomes part of the security and data path. Protect B2 application keys, use a separate restricted key for each tenant or trust boundary, rotate keys, enforce request-size and rate limits, and design the gateway for retries, backpressure, multipart uploads, and failure recovery.

Use a CDN for Branded Object Delivery

Use a CDN when tenants or end users primarily download objects through a branded hostname. A CDN can terminate TLS for your domain, cache eligible responses, and deliver content from locations closer to users.

For a public bucket, the CDN can retrieve public objects from B2 without S3 authentication. For a private bucket, configure the CDN or an edge function to authenticate origin requests. Follow the CDN-specific Backblaze integration guide instead of assuming that a presigned URL created for the standard B2 hostname remains valid after the hostname changes.

A CDN endpoint is not automatically a complete S3-Compatible API endpoint. Do not cache writes, listings, authorization failures, or tenant-specific responses unless you have explicitly designed safe cache rules. Use the official Custom Domain or a re-signing gateway when tenants need authenticated uploads, listings, deletes, multipart operations, or bucket management.

Proxy Public Downloads with NGINX

The following NGINX example exposes a branded hostname for downloads from a public bucket. It is not a configuration for authenticated S3 API requests.

server {
    listen 443 ssl;
    server_name files.example.com;

    ssl_certificate /etc/nginx/tls/files.example.com.crt;
    ssl_certificate_key /etc/nginx/tls/files.example.com.key;

    location / {
        proxy_ssl_server_name on;
        proxy_ssl_name s3.us-west-004.backblazeb2.com;
        proxy_set_header Host s3.us-west-004.backblazeb2.com;
        proxy_pass https://s3.us-west-004.backblazeb2.com/example-public-bucket/;
    }
}

With this configuration, a request for https://files.example.com/photos/image.jpg is forwarded to the path-style B2 URL for example-public-bucket/photos/image.jpg. Review and test URL encoding, range requests, response headers, cache behavior, upload limits, and timeouts before using a proxy in production.

Configure TLS for the Branded Domain

The component that terminates the client's HTTPS connection must present a certificate that covers the branded hostname.

• Backblaze Custom Domain: Install the DNS and ACME challenge records supplied by Backblaze. Backblaze verifies the records and requests the certificate.

• CDN: Follow the CDN provider's process to issue or upload the certificate and validate the domain.

• Self-managed gateway: Issue and renew the certificate through your certificate authority or automated certificate service.

Use HTTPS for all client and upstream connections. Monitor certificate expiration and DNS validation records. If your design uses virtual-hosted-style addressing, ensure that the certificate and DNS configuration cover bucket hostnames.

Test the Branded Endpoint

Test with the same SDKs, tools, object sizes, and request patterns that tenants will use.

• Resolve the endpoint and verify the complete TLS certificate chain.

• Confirm that the SDK uses the correct region and SigV4.

• Test path-style and virtual-hosted-style addressing as applicable.

• Test bucket names with and without periods.

• Upload and download small and large objects.

• Complete, retry, and abort multipart uploads.

• Generate and use presigned upload and download URLs.

• List and delete objects with a restricted application key.

• Test object names containing spaces, Unicode characters, percent signs, and encoded path separators.

• Compare error codes and response headers with requests sent directly to the standard B2 endpoint.

• Verify request logging, rate limits, timeouts, and failure behavior.

Understand the Limitations

• Backblaze Custom Domains require an eligibility review and coordination with Backblaze Sales and Solutions.

• Backblaze charges a one-time setup fee for each approved custom domain.

• All members of the Group associated with a Custom Domain must be in the same region.

• Backblaze currently limits Custom Domains to approved DNS zones that meet its domain-level requirements. Confirm the intended domain with Backblaze before changing production DNS.

• A DNS CNAME alone does not complete the Backblaze custom-domain installation or provide the required TLS and service configuration.

• A CDN is primarily a content-delivery layer, not a replacement for every S3 operation.

• A reverse proxy that changes the hostname, path, query string, signed headers, or payload can invalidate SigV4 authentication.

• A re-signing gateway must securely store credentials and scale with the full data path.

• A branded endpoint does not add S3 features that the B2 S3-Compatible API does not support.

• Applications that do not allow a custom S3 endpoint might not work with either the standard or branded B2 endpoint.

Troubleshooting

Use the following checks when requests to the branded endpoint fail.

Frequently Asked Questions

Can I use my own domain for the B2 S3-Compatible API?

Yes. Eligible Powered By Backblaze partners can request Backblaze Custom Domains. Backblaze evaluates the request, supplies the required DNS records, and requests a TLS certificate after validating the DNS configuration. For download-only services, a CDN with a custom hostname might be a better fit.

How do I keep SigV4 working through a proxy?

Sign the exact hostname, path, query string, headers, body, and region that B2 will validate, and do not modify signed components after signing. If the proxy must change the request or use the standard B2 hostname upstream, authenticate the incoming request and create a new SigV4 signature for the upstream request.

Can I create only a CNAME that points to the B2 endpoint?

Not for a supported authenticated S3 endpoint. A CNAME alone does not configure Backblaze to recognize the domain or provide a matching TLS certificate. Use the Backblaze Custom Domain installation process, a properly configured CDN for content delivery, or a gateway that terminates and re-signs requests.

Should I use a CDN or an S3 API endpoint?

Use a CDN for cached object delivery to end users. Use an approved Backblaze Custom Domain when S3-compatible clients need a branded endpoint. Use a re-signing gateway when your platform must apply its own authentication, authorization, metering, or request transformation.

Additional Resources

• Powered By Backblaze Quickstart Guide

• Custom Domain Installation Process

• Call the Backblaze B2 S3-Compatible API

• S3-Compatible API

• S3-Compatible Application Keys

• Deliver Public B2 Content Through Cloudflare CDN

• Deliver Private B2 Content Through Cloudflare CDN

• Content Delivery Network Integrations