---
title: "Host Aliases"
description: "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."
stack: "Enterprise Stack (commercial) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/enterprise-stack/administration/access-and-permissions/host-alias
generated: 2026-07-20
---
# 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:

| Field | Description |
|-------|-------------|
| `id` | The custom domain (e.g., `tenant1.example.com`) |
| `organization` | The organization ID this alias belongs to |
| `target` | The full resource path in the organization tree |
| `pathPrefix` | Optional path prefix for tenant-level aliases |

## 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

| Operation | Permission |
|-----------|------------|
| Create | `create-host-alias` |
| View | `view-host-alias` |
| Delete | `delete-host-alias` |

### Create a Host Alias

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

**Option: CURL**

**Endpoint:** `POST /v1/{target}/host-alias-api/host-aliases/create`

**Example Request**

```bash
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"
}'
```

**Path Parameters**

- `orgId`: The organization ID (e.g., `waltid`)
- `aliasId`: A unique identifier for this host alias resource (e.g., `tenant1-example-com`)

**Body**

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

**Body Parameters**

- `domain`: _String_ — The custom domain to map. This is the hostname that will route to this organization/tenant.

---

**Response Codes**

- `201` — Host alias created successfully
- `400` — Invalid target path or alias already exists at the location
- `401` — Authentication required
- `403` — Insufficient permissions

### 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.

**Option: CURL**

**Endpoint:** `POST /v1/{target}/host-alias-api/host-aliases/create`

**Example Request**

```bash
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"
}'
```

**Path Parameters**

- `orgId`: The organization ID (e.g., `waltid`)
- `tenantId`: The tenant ID (e.g., `tenant1`)
- `aliasId`: A unique identifier for this host alias resource (e.g., `acme-credentials`)

---

**Response Codes**

- `201` — Host alias created successfully

### View a Host Alias

Retrieve information about an existing host alias.

**Option: CURL**

**Endpoint:** `GET /v1/{target}/host-alias-api/host-aliases/view`

**Example Request**

```bash
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}'
```

---

**Example Response**

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

**Response Fields**

- `_id`: The full path of the host alias resource in the organization tree
- `domain`: The custom domain mapped by this alias

---

**Response Codes**

- `200` — Success
- `404` — No host alias found at the target path
- `401` — Authentication required
- `403` — Insufficient permissions

### Delete a Host Alias

Remove an existing host alias mapping.

**Option: CURL**

**Endpoint:** `DELETE /v1/{target}/host-alias-api/host-aliases/delete`

**Example Request**

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

---

**Response Codes**

- `200` — Host alias deleted successfully
- `404` — No host alias found at the target path
- `401` — Authentication required
- `403` — Insufficient permissions

## 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.

**Info:**

DNS changes can take up to 48 hours to propagate globally. Test your configuration using `dig` or `nslookup` before relying on the custom domain.

## 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](https://docs.walt.id/enterprise-stack/administration/organizations/overview.md) — Learn about organization structure
- [Tenants](https://docs.walt.id/enterprise-stack/administration/tenants/overview.md) — Learn about multi-tenancy
- [RBAC Model](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/rbac-model.md) — Understand permissions and roles
- [Roles](https://docs.walt.id/enterprise-stack/administration/access-and-permissions/roles/overview.md) — Configure roles with host alias permissions