domain.claim(hostname: string, options?: RequestScope): Promise<CustomDomainResource | null>Attaches a hostname to the workspace and resolves the DNS records that prove you own it. Nothing is served on the domain until those records are published and a verify pass succeeds.
A workspace holds at most one custom domain. Claiming again replaces a pending claim and resets its challenge, which throws away an in-flight verification. Re-claiming a hostname that is already active is a no-op and resolves it unchanged.
The hostname is canonicalised before validation, so casing and a trailing dot are tolerated. A hostname another workspace has already verified is refused permanently, and custom domains require a paid plan.
Example
const domain = await envless.workspace.domain.claim('vault.example.com')
for (const record of domain?.records ?? []) {
console.log(record.type, record.name, record.value)
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | string | Yes | Hostname to attach, canonicalised by the API before validation. |
options.signal | AbortSignal | No | Cancels the request. |
Returns
CustomDomainResource for the claimed hostname carrying the ownership records to publish, or null when the API returns no domain.
Worth knowing
- A malformed hostname and a hostname another workspace already verified both fail with the same
domain.invalidcode. - Status 402 with
plan.upgrade_requiredmeans the workspace plan does not include custom domains.
Required scopes
workspace:write
Underlying endpoint
POST /workspace/domain
Request and response schema, every error code, and a live playground.
In Python
envless.workspace.domain.claim()
The same method in envless-sdk, the Python SDK, with the same request, retries and errors.
In Ruby
Envless.workspace.domain.claim
The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.
In PHP
$envless->workspace->domain->claim()
The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.