Workspace

$envless->workspace->domain->claim()

Attach a hostname to the workspace

php
/** @return CustomDomainResource|null */
public function claim(
    string $hostname,
    int|float|null $timeout = null,
): ?array

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

php
use Envless\Envless;

$envless = new Envless();

$domain = $envless->workspace->domain->claim('vault.example.com');

foreach ($domain['records'] ?? [] as $record) {
    echo "{$record['type']} {$record['name']} {$record['value']}", PHP_EOL;
}

Parameters

ParameterTypeRequiredDescription
$hostnamestringYesHostname to attach, canonicalised by the API before validation.
$timeoutint|floatNoSeconds each attempt of this call may take, the response body included, before it throws Envless\Exception\NetworkException with isTimeout() true. Overrides the client's timeout for this call, and 0 turns the limit off.

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.invalid code.
  • Status 402 with plan.upgrade_required means 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.