---
sidebar_label: Custom domains
doc_id: 5bbec3a5-e3ad-4b45-8766-d0a98333c08a
description: >-
  Configure custom domains to replace auto-generated URLs with user-friendly
  names for your application scopes.
keywords:
  - custom domains
  - DNS configuration
  - load balancer
  - scope mapping
  - FQDN
---
# Custom domains

## What is a custom domain?

**Custom domains** allow you to define one or more domains and associate them with a scope. These **custom domains do not
replace the automatically generated domain** but serve as an additional option.

When you create a scope, nullplatform automatically generates a domain using the namespace, application, and scope
slugs, along with a hash to prevent collisions.

> For example, if your:
>- organization is called *Crypto Inc*,
>- namespace is *Billing*,
>- application is *Payments API*, and 
>- scope is *Production Argentina*; 
>
> The domain generated by nullplatform would look something like this:<br/>`billing-payments-api-production-argentina-$hash.crypto-inc.com`

While this domain allows traffic to be routed to the scope, it is not a user-friendly name suitable for public use.
For that reason, you can create custom domains and associate them with your scopes.

## Configuring a custom domain

To configure a custom domain, go to **Platform settings** and select **Custom Domains** under the **Networking** menu.

The setup involves:

- Making sure your certificate supports the new domain before setting it up.
- Entering the fully qualified domain name (FQDN) without the protocol (`http`, `https`). For example, `api.crypto-inc.com`.
- Selecting the application and scope to associate the domain with.

:::note Need to know
Each scope can have multiple custom domains, but a custom domain can only be assigned to a single scope.
:::

For more details, see the [Custom domain API reference](/docs/scope-custom-domain-api-index).

## What happens when a domain is associated with a scope?

When a domain is associated with a scope, nullplatform configures a rule in the relevant load balancer (e.g., ALB for
AWS instances, Ingress for Kubernetes) to route all requests for that domain to the scope’s infrastructure.

:::info Important
- The user setting up the domain is responsible for creating the domain and configuring traffic routing to the appropriate load balancer.
- Like any changes made to scopes, the new domain will take effect starting from the next deployment.
:::


## Troubleshooting

### Verify DNS configuration

If your custom domain isn’t working, start by checking your DNS settings:

- **Register the domain**: Make sure your custom domain is properly registered with your DNS provider.
- **Create necessary DNS records**:  
  - Ensure that DNS records point to the correct infrastructure endpoint, whether that’s an ALB, API Gateway, or another ingress controller.
  - **Example**: If you're using AWS API Gateway, a CNAME should point to the gateway's domain name.


### Check the gateway objects

If you're using Kubernetes with Istio, verify that the cluster is configured to accept the custom domain.

- Check the Istio Gateway resources, such as `gateway-private` and `gateway-public`.
- These gateway objects must be configured to route requests for your custom domains.

> For example, if HTTP routes are not working, it's often necessary to review the Gateway configuration.

Within the gateway objects:

- Ensure the **domain validation** is correctly set to match your custom domains.
- Confirm that the **TLS certificates** associated with the gateway are valid and cover all configured custom domains.

An invalid or missing domain entry or certificate could prevent traffic from reaching your services.