Skip to content

Custom Domains

Public Forge apps can be accessed via custom domains in addition to their auto-generated *.ptkl.app subdomain.

Auto-Generated Subdomain

When a Forge app is created with type: "public", it automatically receives a subdomain:

happy-fox.ptkl.app

This subdomain is immediately active — no DNS configuration is needed. It's stored as basehostname in the app's domain configuration.

Adding a Custom Domain

Custom domains allow you to serve your app from your own domain (e.g. app.example.com).

Step 1: Register the Domain

Add a custom domain to your app via the API:

POST /luma/appservice/v1/forge/:ref/domain

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

The API returns a validation key — a base64-encoded string used to verify domain ownership:

{
  "domain": "app.example.com",
  "validationKey": "YTFiMmMzZDQ6MjAyNjAyMTA6YXBwLmV4YW1wbGUuY29t"
}

At this point the domain is stored as unvalidated and is not yet active.

Step 2: Create a TXT Record

Add a TXT DNS record on your domain to prove ownership:

Record Type Name Value
TXT app.example.com The validationKey returned by the API

Note

DNS propagation can take anywhere from a few minutes to 48 hours depending on your DNS provider. Most providers propagate within 5–15 minutes.

Step 3: Verify the Domain

Once the TXT record is in place, trigger verification:

POST /luma/appservice/v1/forge/:ref/domain/verify

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

The platform performs a DNS TXT lookup on the domain and checks for an exact match with the expected validation key. On success, the domain becomes active.

If verification fails (e.g. DNS hasn't propagated yet), you can retry. If the validation key has expired, refresh it first:

POST /luma/appservice/v1/forge/:ref/domain/refresh

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

Step 4: Point Your Domain

After verification, create a DNS record to route traffic to the platform.

Create a CNAME record pointing to ptkl.app:

Record Type Name Value
CNAME app.example.com ptkl.app

This is the recommended approach — if the platform IP ever changes, your domain will follow automatically.

Coming Soon

Support for apex / root domains is coming soon. In the meantime, we recommend using a subdomain (e.g. app.example.com) with a CNAME record.

Domain States

Domains go through two states:

State Description
Unvalidated Domain has been added but TXT verification is pending. Not serving traffic.
Active TXT verification passed. Domain is live and serving the app.

Removing a Domain

To remove a custom domain:

DELETE /luma/appservice/v1/forge/:ref/domain

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

After removal, remember to clean up the CNAME/A and TXT records from your DNS provider.

Summary

The complete setup process:

Step Action Where
1 Register the domain via API Platform
2 Create TXT record with validation key Your DNS provider
3 Verify domain ownership via API Platform
4 Create CNAME → ptkl.app (subdomain). Apex domains coming soon. Your DNS provider