Skip to content

Domains

An environment is served on exactly one host, which is its issuer: its platform host, such as your-app.auth.dev.seek.services, or a custom domain of yours, such as id.your-app.com. A domain becomes the environment’s once a DNS record proves you control it; then moving the issuer there is a separate step. See Custom domains for the whole procedure. Custom domains are on paid plans: 2 on Pro and 10 on Scale, across the workspace.

The domain object:

Field Type Meaning
id uuid Used as :domain below.
domain string
verified_at string
host, issuer string The host and issuer the environment has on this domain.
primary boolean Whether the environment is served on this domain now.
GET/v1/environments/:id/domainsviewer
{
"host": "your-app.auth.dev.seek.services",
"issuer": "https://your-app.auth.dev.seek.services",
"platform_host": "your-app.auth.dev.seek.services",
"platform_issuer": "https://your-app.auth.dev.seek.services",
"domains": []
}

host and issuer are where the environment is served now; platform_host and platform_issuer are its platform address, where it can always go back to.

POST/v1/environments/:id/domainsadmin
Field Type Meaning
domain string A full domain name such as id.your-app.com. It is trimmed, lowercased and loses a trailing dot.

Nothing is stored yet: the answer is the records to create at your DNS provider.

POST /v1/environments/{env}/domains
{ "domain": " ID.your-app.com. " }
200
{
"domain": "id.your-app.com",
"verified": false,
"records": [
{ "type": "TXT", "name": "_seek-auth.id.your-app.com", "value": "…", "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" }
]
}

The TXT value is derived from the environment and the name: it is the same every time you ask, and differs between environments. Copy it from the answer.

Status code When
400 bad_request “enter a domain such as id.example.com”, “a domain is letters, digits and hyphens separated by dots, with no scheme, port or path”, “enter a full domain name, not a single label or an address”, “this name belongs to the platform itself”
402 plan_limit The plan has no room for another custom domain (none on Free).
POST/v1/environments/:id/domains/verifyadmin

The same body. SeekAuth looks the TXT record up (over DNS-over-HTTPS).

Answer Meaning
200 with "verified": false and the records DNS does not show the record yet. Try again once it has spread.
201 with the domain object and "verified": true The domain is now the environment’s.
200 with the domain object and "verified": true It already was.
Status code When
402 plan_limit The plan has no room for another custom domain.
409 conflict “this domain is already in use by another environment”
502 upstream_error The DNS resolver did not answer.
PUT/v1/environments/:id/issueradmin
Field Type Meaning
domain_id uuid or null A verified domain of the environment, or null for its platform host.
confirm string The environment’s current host.
PUT /v1/environments/{env}/issuer
{ "domain_id": "…", "confirm": "your-app.auth.dev.seek.services" }

The answer is the environment.

Status code When
400 bad_request “changing the login address changes the issuer for every client: repeat the current host in confirm to go ahead”
404 not_found Unknown domain_id.
409 conflict “another environment is served on this host”
DELETE/v1/environments/:id/domains/:domainadmin

:domain is the domain’s id. Answers 204, or 404. A domain the environment is served on cannot be removed: move the issuer first (409 “the environment is served on this domain: move it to another address first”).