Lexicon Garden

at.happyproto.server.addDomain

Add a custom domain to one of the caller's instances. It starts pending, with the DNS records to publish. Customers only.

Repository @happyproto.at did:plc:mo7vq4jbioxwafy5zkcc3eux namespace authority
Details · procedure
Kindprocedure
Authorityserver.happyproto.at
Indexed
Compare Edit in builder → Fork →

Procedure

procedure · POST

Input

application/json

hostname

requiredstring

The hostname, such as app.example.com. No scheme, port or path.

idempotencyKey

requiredstring

A UUID the client generates once per intended change and resends on every retry of it, so a retry gets the original reply instead of acting twice.

instanceId

requiredstring

The instance's UUID.

Output

application/json

domain

requiredref
Reference

Errors

AuthRequired

This endpoint requires an authenticated caller.

Forbidden

The caller is not a HappyProto customer, or the provisioner refused them.

InvalidRequest

instanceId or idempotencyKey is not a UUID, or hostname is missing or too long.

NotFound

No such instance or domain, or it is not the caller's. The cases are indistinguishable.

NotAvailable

Custom domains are not switched on yet.

InvalidSlug

Passed through from the provisioner.

SlugTaken

Passed through from the provisioner.

NotEntitled

Passed through from the provisioner.

InstanceLimit

Passed through from the provisioner.

NoCapacity

Passed through from the provisioner.

OperationInProgress

Passed through from the provisioner: the instance is already changing, or a request with this idempotencyKey is still running.

InvalidHostname

The hostname is not a valid public hostname: no scheme, port, path, wildcard or IP address.

PlatformHostname

The hostname is HappyProto's own, or under one of its domains.

DomainExists

The instance already has this hostname.

DomainLimit

The instance already has as many custom domains as it may.

TooSoon

Passed through from the provisioner.

DomainIsPrimary

Passed through from the provisioner.

NotVerified

Passed through from the provisioner.

CertificateNotReady

Passed through from the provisioner.

VersionTooOld

Passed through from the provisioner.

Upstream

The provisioner is unreachable, not configured, or answered with an error it does not explain to callers, or the job could not be started.

#altRecord

object

Properties

type

requiredstring

A.

value

requiredstring

The instance host's public IPv4.

#checks

object

Properties

checkedAt

requiredstring

When the check ran.

ownership

requiredstring

Whether the TXT record carries this claim's token.

  • knownValues: ok | missing | error

pointing

string

Whether the hostname resolves to the instance's host. Absent when the check didn't get that far, such as when the TXT record was missing.

  • knownValues: ok | elsewhere | error

#domain

object

A custom domain on one of the caller's instances.

Properties

checks

ref

The latest DNS check. Absent until the first check has run.

Reference

createdAt

requiredstring

When the domain was added.

expiresAt

string

When a pending claim expires if it is never verified. Absent once verified.

hostname

requiredstring

The hostname, lowercase, internationalized names in punycode.

id

requiredstring

The domain's UUID.

lapsesAt

string

When HappyProto stops serving the domain if its TXT record stays missing. Absent while the record is present.

primary

requiredboolean

Whether this is the instance's primary domain, the one its PUBLIC_URL follows.

records

requiredarray

The DNS records the customer publishes: the TXT that proves ownership, then the CNAME that points the hostname at the instance.

itemsref
Reference

serving

requiredstring

Whether the domain actually works: off until it is verified, issuing while its certificate is ordered, live once it serves over HTTPS.

  • knownValues: routing | issuing | live | failed | off

state

requiredstring

pending: waiting for the DNS records. verified: proven and served. lapsed: the TXT record went missing, and HappyProto stopped serving it; it recovers if the record comes back before expiresAt.

  • knownValues: pending | verified | lapsed

verifiedAt

string

When the domain was first verified.

#record

object

Properties

alt

ref

For an apex name, which cannot hold a CNAME: the A record to publish instead. Absent when the instance's host has no public IPv4.

Reference

name

requiredstring

The record's name.

type

requiredstring

TXT or CNAME.

value

requiredstring

The record's value.

Similar lexicons

semantic match

Lexicons whose schemas describe something close to this one. Check them before publishing a new one that overlaps.

  • at.happyproto.server.checkDomain

    procedure

    Check a custom domain's DNS records now, rather than at the next scheduled check. Customers only.

  • at.happyproto.server.listDomains

    query

    The domains of one of the caller's instances: its platform subdomain and any custom domain. Customers only.

  • at.happyproto.server.setPrimaryDomain

    procedure

    Make a domain the primary of one of the caller's instances: a verified custom domain that is serving, or the platform subdomain. The instance restarts onto it. Customers only.

  • place.wisp.v2.domain.claim

    procedure not from the namespace authority

    Claim a custom domain for the authenticated DID. Returns DNS setup instructions.

  • at.happyproto.server.removeDomain

    procedure

    Remove a custom domain from one of the caller's instances. HappyProto stops serving it. Customers only.