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. |
List domains
Section titled “List domains”{ "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.
Get the DNS records
Section titled “Get the DNS records”| 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). |
Verify a domain
Section titled “Verify a domain”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. |
Move the issuer
Section titled “Move the issuer”| 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” |
Remove a domain
Section titled “Remove a domain”: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”).