#Host Aliases

Host aliases enable custom domain routing in the Enterprise Stack, allowing organizations and tenants to be accessed via their own domain names instead of the default subdomain structure.

#Overview

By default, organizations are accessed using subdomains of the base domain (e.g., myorg.enterprise-sandbox.waltid.dev). Host aliases let you map custom domains to specific organizations or tenants, enabling:

• Custom branding — Use your own domain (e.g., credentials.example.com)
• Tenant isolation — Give each tenant their own subdomain or domain
• Simplified URLs — Shorter, more memorable endpoints for your services

When a request arrives at the Enterprise Stack, the system looks up the incoming host in the host alias table to determine which organization and tenant context to use.

#How It Works

1. A request arrives at tenant1.example.com
2. The system looks up tenant1.example.com in the host alias table
3. The alias maps to organization myorg with path prefix myorg.tenant1
4. All API calls are routed to that organization/tenant context
5. Service URLs (e.g., credential offer URLs) use the custom domain

#Host Alias Structure

A host alias contains:

#Managing Host Aliases

Host aliases are managed via the Host Alias API. You need the appropriate permissions to create, view, or delete aliases.

#Required Permissions

#Create a Host Alias

Create a host alias to map a custom domain to an organization or tenant.

curl -X 'POST' \
  'https://{orgId}.enterprise.sandbox.walt.id/v1/{aliasId}/host-alias-api/host-aliases/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "domain": "tenant1.example.com"
}'

{
  "domain": "tenant1.example.com"
}

#Create a Tenant-Level Host Alias

You can also create host aliases at the tenant level, allowing each tenant to have its own custom domain.

curl -X 'POST' \
  'https://{orgId}.enterprise.sandbox.walt.id/v1/{tenantId}.{aliasId}/host-alias-api/host-aliases/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "domain": "credentials.acme.com"
}'

#View a Host Alias

Retrieve information about an existing host alias.

curl -X 'GET' \
  'https://{orgId}.enterprise.sandbox.walt.id/v1/{aliasId}/host-alias-api/host-aliases/view' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}'

{
  "_id": "waltid.tenant1-example-com",
  "domain": "tenant1.example.com"
}

#Delete a Host Alias

Remove an existing host alias mapping.

curl -X 'DELETE' \
  'https://{orgId}.enterprise.sandbox.walt.id/v1/{aliasId}/host-alias-api/host-aliases/delete' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}'

#DNS Configuration

After creating a host alias, you need to configure your DNS to point the custom domain to the Enterprise Stack.

#Option 1: CNAME Record (Recommended)

Create a CNAME record pointing your custom domain to the Enterprise Stack base domain:

tenant1.example.com.  CNAME  enterprise-sandbox.waltid.dev.

#Option 2: A Record

If you cannot use CNAME (e.g., for apex domains), create an A record pointing to the Enterprise Stack IP address. Contact support for the current IP addresses.

#Use Cases

#Multi-Tenant White-Labeling

Give each tenant their own branded domain for credential issuance:

# Tenant 1: ACME Corp
acme.credentials.example.com → waltid.tenant-acme

# Tenant 2: Globex Inc  
globex.credentials.example.com → waltid.tenant-globex

#Service-Specific Domains

Use different domains for different services:

# Issuer service
issuer.example.com → waltid.tenant1.issuer1

# Verifier service
verify.example.com → waltid.tenant1.verifier1

#Regional Deployments

Route regional domains to region-specific tenants:

eu.example.com → waltid.tenant-eu
us.example.com → waltid.tenant-us

#Impact on Service URLs

When a host alias is active, all generated URLs (such as credential offer URLs) will use the custom domain instead of the default subdomain structure.

Without host alias:

openid-credential-offer://waltid.enterprise-sandbox.waltid.dev/?credential_offer_uri=...

With host alias (tenant1.example.com):

openid-credential-offer://tenant1.example.com/?credential_offer_uri=...

This ensures that wallets and other clients interact with your branded domain throughout the entire credential lifecycle.

#Related

• Organizations — Learn about organization structure
• Tenants — Learn about multi-tenancy
• RBAC Model — Understand permissions and roles
• Roles — Configure roles with host alias permissions