Custom Domains

Serve hosted login pages and auth endpoints from your own domain instead of api.bulwarkauth.com.

How it works

Custom domains are configured per application. When a request arrives at api.bulwarkauth.com, Bulwark resolves the Host header to the correct tenant and serves that tenant's branding and configuration.

With a custom domain configured, your users see:

https://login.myapp.com/login
https://login.myapp.com/signup

instead of:

https://api.bulwarkauth.com/hosted/myapp/login

DNS configuration

Create a CNAME record pointing your custom domain to api.bulwarkauth.com:

| Type | Name | Value | |------|------|-------| | CNAME | login.myapp.com | api.bulwarkauth.com |

DNS propagation typically takes a few minutes but can take up to 48 hours depending on TTL settings.

Registering the custom domain

After creating the DNS record, register the domain via the API:

PUT /api/v1/settings/applications/{id}/domain
Authorization: Bearer <admin-token>
X-Bulwark-Tenant: <tenant-id>

{
  "domain": "login.myapp.com"
}

Response

{
  "domain": "login.myapp.com",
  "status": "pending",
  "verified_at": null,
  "ssl_status": "provisioning"
}

Bulwark will:

  1. Verify the CNAME record points to api.bulwarkauth.com
  2. Provision a TLS certificate via Let's Encrypt
  3. Set status to active once both steps complete

Poll the status endpoint to track progress:

GET /api/v1/settings/applications/{id}/domain

{
  "domain": "login.myapp.com",
  "status": "active",
  "verified_at": "2026-03-20T10:05:00Z",
  "ssl_status": "active"
}

| status value | Meaning | |----------------|---------| | pending | Waiting for DNS verification | | active | Domain is live | | failed | DNS check or TLS provisioning failed |

Pages served on the custom domain

Once active, the following paths are available on your custom domain:

| Path | Description | |------|-------------| | /login | Hosted login page | | /signup | Hosted signup page | | /forgot-password | Password reset request | | /verify-email | Email verification handler |

These paths serve the same content as the api.bulwarkauth.com/hosted/{slug}/* equivalents, using your tenant's branding settings.

Branding

Branding (logo, colors, app name) is loaded from the application's settings. See Hosted Login — Branding for the configuration API.

Custom domain pages apply the same branding as the hosted pages at api.bulwarkauth.com/hosted/{slug}/*.

Removing a custom domain

DELETE /api/v1/settings/applications/{id}/domain
Authorization: Bearer <admin-token>
X-Bulwark-Tenant: <tenant-id>

Response — 204 No Content

After removal, traffic to the custom domain will no longer be resolved by Bulwark. Update or remove your DNS record accordingly.

Notes

  • Each application supports one custom domain.
  • Wildcard domains are not supported.
  • The custom domain is used only for hosted pages. API calls from your SDK continue to target api.bulwarkauth.com directly.
  • TLS certificates are auto-renewed by Bulwark. No manual renewal is required.