Skip to navigation

A custom domain is a hostname you own, such as assets.example.com, that serves a public bucket instead of the bucket’s test Public Access URL. IBEE gets an HTTPS certificate for the hostname automatically. Use it for production downloads, website assets and links you’ll publish, because the Public Access URL is rate-limited and meant for testing.

When to use a custom domain

You want to…UseNotes
Serve a public bucket’s files on your own hostnameBucket custom domain (this page)Files come straight from the bucket
Serve files fast worldwide, with cachingA CDN distribution with its own custom domainDon’t also put the same hostname on the bucket
Quickly test public accessThe bucket’s Public Access URLRate-limited; not for production
Share private filesPresigned URLsCustom domains serve only public buckets

How it works

  1. You create a CNAME record — a DNS entry that says “this hostname is an alias of that one” — pointing your hostname at the target IBEE shows you (it ends in .ibee.zone).
  2. You add the hostname in the bucket’s Custom Domains tab. IBEE checks that the CNAME already points to the target.
  3. IBEE gets an HTTPS certificate (from Let’s Encrypt) and starts serving the bucket on your hostname: https://assets.example.com/OBJECT-KEY.

Before you begin

  • A bucket with Public Access turned on. See Bucket Policies → Public access. Every object in a public bucket can be read by anyone.
  • Access to your domain’s DNS settings (at your registrar or DNS provider).
  • A hostname that isn’t used by another bucket, such as a subdomain like assets.example.com.
  • Billing in good standing: custom domains are a separately billed add-on, and the portal checks your billing before it adds one.

Add a custom domain

1

Open Custom Domains

Open the bucket, click Settings, then Custom Domains, and click Add Domain. The Add Custom Domain dialog says Connect your bucket to a custom domain.

2

Copy the CNAME target

Step 1 of the dialog reads Add a CNAME record in your DNS pointing to: and shows the target, which ends in .ibee.zone. Click Copy.

3

Create the CNAME record

At your DNS provider, add a record:

TypeName (host)Value (target)
CNAMEassets (for assets.example.com)The target you copied

Wait until the record resolves. Check from a terminal:

dig +short assets.example.com CNAME

It should print the target. Most providers publish changes within minutes; some take longer.

4

Enter your domain

In Step 2 — Enter your domain after the CNAME record is added. — type the full hostname, such as assets.example.com.

5

Add it

Click Add Domain. If the CNAME is in place, the toast Domain added. SSL certificate is being prepared. appears and the domain is listed with its status.

Add a custom domain with the API

Create the CNAME first, then:

# See the CNAME target and any existing domains (404 if the bucket has none yet)
curl "https://api.ibee.ai/v1/object-storage/buckets/my-bucket/custom-domains?workspace_id=YOUR-WORKSPACE-ID" \
-H "Authorization: Bearer $IBEE_API_TOKEN"
# Add the domain
curl -X POST "https://api.ibee.ai/v1/object-storage/buckets/my-bucket/custom-domains?workspace_id=YOUR-WORKSPACE-ID" \
-H "Authorization: Bearer $IBEE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"domain": "assets.example.com"}'

Remove one with DELETE …/custom-domains/assets.example.com. Scopes: object-storage.read, object-storage.write and, to remove a domain, object-storage.delete.

Verify

The status in the Custom Domains list moves to Active:

StatusMeaning
Pending DNS VerificationThe CNAME doesn’t point to the target yet
Provisioning SSLDNS is correct; the HTTPS certificate is being issued
ActiveThe hostname serves the bucket over HTTPS
DNS needs attentionThe DNS record no longer points to the target
SSL needs attentionThe certificate couldn’t be set up
ErrorSetup failed

Then fetch a file:

curl -I https://assets.example.com/images/logo.png

HTTP/2 200 means it works. A key that doesn’t exist returns 404.

Remove a custom domain

Click Remove next to the domain, then Remove Domain in the Remove Custom Domain dialog. The hostname stops serving the bucket. Delete the CNAME record at your DNS provider afterwards.

Limits and billing

Value
Bucket accessMust be public
DNS recordCNAME to the ….ibee.zone target, in place before you add the domain
CertificateIssued automatically; no upload needed
One hostnameCan serve one bucket only
BillingSeparate add-on; the portal checks billing first
DownloadsBilled as Object Storage egress. See Pricing.
Rate limitNot subject to the Public Access URL’s limit of 50 requests per second
Interrupted registrationA hostname held by an unfinished attempt is released after 30 minutes

Troubleshooting

You seeWhat it meansWhat to do
Bucket must be public to add custom domain, or the CNAME target shows as unavailablePublic Access is offTurn on Public Access in Settings → General.
CNAME verification failed: …The CNAME doesn’t resolve to the target yetCheck the record with dig, wait for DNS to update, then add the domain again.
Domain assets.example.com is already registered to another bucketThe hostname is used elsewhereRemove it from the other bucket, or use another hostname.
… registration is already in progress; retry laterAn earlier attempt is still runningWait a few minutes and check the list. An unfinished attempt is released after 30 minutes.
A billing message instead of the dialogYour balance or credit limit can’t cover the add-onAdd credit under Billing, then try again.
Stuck in Pending DNS VerificationThe record is wrong, for example the provider added your domain to the end of the targetMake sure the value is exactly the target shown in the portal.
DNS needs attentionThe CNAME was changed or removedRestore the record.
403 for every filePublic Access was turned off laterTurn it back on.
404 for a fileThe key is wrong (keys are case-sensitive)Check the full key.