def claim(hostname, timeout: nil)def claim: (String hostname, ?timeout: seconds?) -> custom_domain_resource?Attaches a hostname to the workspace and returns 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 returns 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
require "envless/sdk"
domain = Envless.workspace.domain.claim("vault.example.com")
domain&.fetch(:records)&.each do |record|
puts "#{record[:type]} #{record[:name]} #{record[:value]}"
endParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
hostname | String | Yes | Hostname to attach, canonicalised by the API before validation. |
timeout: | Integer | Float | Rational | No | Seconds each attempt of this call may take, redirects and the response body included, before it raises Envless::NetworkError with timeout? set. Overrides the client's timeout for this call, and 0 turns the limit off. |
Returns
custom_domain_resource for the claimed hostname carrying the ownership records to publish, or nil 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 TypeScript
envless.workspace.domain.claim()
The same method in @goenvless/sdk, with the same request, retries and errors.