Domains and basic auth

A domain is a hostname routed to one app, or to one service and path of it. certProvider picks how it gets HTTPS: letsencrypt, cloudflare (proxied, origin left alone), custom (a certificate installed on the host, see Servers) or none.

Basic auth is a separate grant, manage_basic_auth. A login applies to every domain of the app within seconds, no redeploy.

Domains

domains

Any signed-in principal. Returns [Domain!].

Domains in the active team, primary first. Optionally filtered to one project.

query {
  domains(appId: "prj_9f1c2ab7d3e4f5a6") {
    id
    name
    status
    ssl
    primary
  }
}

addDomain

Needs manage_domains. Returns Domain.

Attach a hostname to an app. config sets the routing (port, service, path prefix, www redirect) and the certificate provider; omit it for the defaults.

mutation {
  addDomain(appId: "prj_9f1c2ab7d3e4f5a6", name: "shop.example.com", config: { port: 3000, www: toThis }) {
    id
    name
    status
    ssl
  }
}

updateDomain

Needs manage_domains. Returns Domain.

Apply a full edit to a domain and return the updated domain (reloaded).

mutation {
  updateDomain(
    id: "dom_9f1c2ab7d3e4f5a6"
    patch: { pathPrefix: "/api", stripPrefix: true }
  ) {
    id
    name
    status
    ssl
    primary
  }
}

setPrimaryDomain

Needs manage_domains. Returns Boolean.

Make this domain its app's primary (canonical) host. Returns true.

mutation {
  setPrimaryDomain(id: "dom_9f1c2ab7d3e4f5a6")
}

verifyDomain

Needs manage_domains. Returns Domain.

Re-check the domain's DNS and (re)issue its certificate. A check that finds the host proxied through Cloudflare also moves a certificate-less domain onto the cloudflare provider.

mutation {
  verifyDomain(id: "dom_9f1c2ab7d3e4f5a6") {
    id
    name
    status
    ssl
    primary
  }
}

removeDomain

Needs manage_domains. Returns Boolean.

Remove the domain so it stops routing. Returns true.

mutation {
  removeDomain(id: "dom_9f1c2ab7d3e4f5a6")
}

dismissImportedDomains

Needs manage_domains. Returns Boolean.

Stop telling this app that its addresses changed when it was imported: clears importedFrom on every one of its domains. Per app on purpose - a migration brings over many, and one blanket dismissal would hide the fact on every app nobody has looked at yet.

mutation {
  dismissImportedDomains(appId: "prj_9f1c2ab7d3e4f5a6")
}

Basic auth

basicAuthUsers

Any signed-in principal. Returns [BasicAuthUser!].

Basic-auth users of an app, alphabetical by username (requires manage_domains).

query {
  basicAuthUsers(appId: "prj_9f1c2ab7d3e4f5a6") {
    id
    username
  }
}

addBasicAuthUser

Needs manage_basic_auth. Returns BasicAuthUser.

Add a basic-auth user to an app. The login is required on every one of its domains within seconds - the routing is re-applied to the running container, no redeploy needed.

mutation {
  addBasicAuthUser(
    appId: "prj_9f1c2ab7d3e4f5a6"
    password: "correct-horse-battery-staple"
    username: "ada"
  ) {
    id
    username
  }
}

updateBasicAuthUserPassword

Needs manage_basic_auth. Returns BasicAuthUser.

Change a basic-auth user's password. The new password is live on every domain of the app within seconds (the old one stops working).

mutation {
  updateBasicAuthUserPassword(
    id: "user_9f1c2ab7d3e4f5a6"
    password: "correct-horse-battery-staple"
  ) {
    id
    username
  }
}

revealBasicAuthPassword

Needs manage_basic_auth. Returns String.

Reveal one credential's password. A basic-auth login is handed to a person, so whoever may change it may also read it back, otherwise the only answer to "what is the password?" is to reset it and lock everyone out. A mutation, not a query, so it is never cached or prefetched.

mutation {
  revealBasicAuthPassword(id: "bau_9f1c2ab7d3e4f5a6")
}

removeBasicAuthUser

Needs manage_basic_auth. Returns Boolean.

Remove a basic-auth user, so its login stops working within seconds. Removing the last one drops the login prompt entirely. Returns true.

mutation {
  removeBasicAuthUser(id: "user_9f1c2ab7d3e4f5a6")
}

See also