Skip to content

Custom domains

Every environment has a login address on SeekAuth’s domain, your-app.auth.dev.seek.services (and your-app-dev.auth.dev.seek.services in development). On a paid plan an environment can be served on a domain of yours instead, such as id.your-app.com: the hosted login page, the endpoints, the issuer in every token.

Plan Custom domains, across the workspace
Free none
Pro 2
Scale 10

Each step takes the admin role, on the Domains page of the environment or with the management API.

POST/v1/environments/:id/domainsadmin
{ "domain": "id.your-app.com" }
{
"domain": "id.your-app.com",
"verified": false,
"records": [
{ "type": "TXT", "name": "_seek-auth.id.your-app.com", "value": "<token>", "purpose": "proves the domain is yours" },
{ "type": "CNAME", "name": "id.your-app.com", "value": "your-app.auth.dev.seek.services", "purpose": "sends the domain's traffic to this service" }
]
}

Create both records at your DNS provider:

  • the TXT record at _seek-auth. and your domain, with the token as its value. The token is the same every time you ask, and differs per environment, so copy it from this answer;
  • the CNAME record from your domain to the environment’s own platform host.

Nothing is stored at this step: the domain becomes the environment’s only when the TXT record proves it, so nobody can hold a name they do not control. A domain is a full name of two labels or more, without scheme, port or path; SeekAuth’s own names are refused.

Once the records are published:

POST/v1/environments/:id/domains/verifyadmin
{ "domain": "id.your-app.com" }

While the TXT record cannot be found yet, the answer is 200 with "verified": false and the records again; DNS can take a while to show a new record, so try again later. When it is found, the answer is 201 with the domain, now the environment’s:

{
"id": "<domain id>",
"domain": "id.your-app.com",
"verified_at": "…",
"host": "id.your-app.com",
"issuer": "https://id.your-app.com",
"primary": false,
"verified": true
}

A domain that another environment already has answers 409.

A verified domain is not used until you move the environment to it. This is the step that changes things for your apps:

PUT/v1/environments/:id/issueradmin
{ "domain_id": "<domain id>", "confirm": "your-app.auth.dev.seek.services" }

confirm repeats the host the environment is on now. What happens:

  • The issuer changes for every client of every app of the group: tokens now say "iss": "https://id.your-app.com", and the discovery document, the keys and every endpoint are on the new host. Give every app, and every backend that verifies tokens, the new issuer.
  • The old host stops answering. An app still configured with it cannot log anyone in.
  • Hosted-page sign-ins start over. The login page’s cookie belongs to the old host, so users who were signed in there sign in again once.

To go back to the platform host, send "domain_id": null, with the current host (now your domain) in confirm.

A TLS certificate is only ever issued for a domain an environment is served on, so a name that points at SeekAuth without being an environment’s (one left behind, say) cannot be claimed by anyone.

DELETE/v1/environments/:id/domains/:domainadmin

:domain is the domain’s id. A domain the environment is served on cannot be removed (409): move the issuer elsewhere first.

  • Passkeys belong to the environment’s passkey domain, and a page can use them only on that domain or under it. If the passkey domain is the old login host, the login page on the new domain cannot use them. Choose the passkey domain with the move in mind, before users make passkeys (see Passkeys).
  • Social providers send users back to the issuer’s /callback/{provider}. After a move, register the new callback addresses at each provider (Social providers).
  • Changing the group’s slug moves only the platform host; an environment on a custom domain stays there.