Domains

Reserve the single free testing subdomain of an application, add custom domains and verify their ownership with a DNS TXT record.

  • Availability: Planned
  • Evidence: Read from source
  • Reference

Operations

Operation Request Capability Retry
domains.list GET /v1/applications/{application}/domains application.read
domains.reserve PUT /v1/applications/{application}/domains/testing domain.manage natural
domains.add POST /v1/applications/{application}/domains domain.manage key
domains.verify POST /v1/applications/{application}/domains/{domain}/verify domain.manage natural
domains.remove DELETE /v1/applications/{application}/domains/{domain} domain.manage natural

The testing subdomain

Every application has exactly one free testing subdomain, served over HTTPS under the tenant zone the operator configured.

JSON
{ "label": "shop" }

The label matches ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$. Repeating the request with the same label answers the same reservation; another label replaces it. A label another application holds is 409 DOMAIN_CONFLICT.

The tenant zone is configuration. It is chosen so that untrusted tenant content is isolated from platform and administration cookies, and this site does not name it.

Custom domains

JSON
{ "hostname": "shop.example.com", "environment": "production" }

A custom domain starts pending and serves nothing until it is verified. The answer carries the record to publish:

Member of verification Meaning
method dns-txt
record The fully qualified name of the TXT record
value The verification token. It proves ownership only and is not a credential.
checked, observed The time of the last check and the TXT values it saw

Publish the TXT record, then call domains.verify. While the record is absent or wrong the answer is 409 DOMAIN_UNVERIFIED, and observed shows what the check found. Verifying a verified domain answers it unchanged. If DNS cannot be reached the answer is 502 UPSTREAM_UNAVAILABLE.

Domain state Meaning
reserved A testing subdomain
pending A custom domain awaiting verification
verified Ownership proven; the domain serves its environment
failed Verification failed

tls reports the certificate: pending, issued or failed.