---
title: "Connect a custom domain to a workspace"
method: POST
path: "/account/domains"
---

# Connect a custom domain to a workspace

`POST /account/domains`

## Request

- Base URL: `https://api.eurobase.dev`
- URL: `https://api.eurobase.dev/account/domains`
- Auth: none declared

Workspace owner only, within the workspace plan limit. With projectId the domain serves that project once its _acme-challenge CNAME is verified and its certificate is issued; without it the domain waits in the workspace and serves nothing.

## Request body

- WorkspaceDomainRequest
  - `organizationId` string, required
  - `hostname` string, required
  - `projectId` string, nullable: The project the domain serves; omitted or null to add it unlinked

## Response `201`

Domain connected, waiting for its DNS records

- ProjectDomainResponse
  - `domain` ProjectDomain, required
    - `id` string, required
    - `hostname` string, required
    - `status` 'pending' | 'issuing' | 'active' | 'failed', required
    - `statusReason` 'verification_timeout' | 'certificate_failed' | 'challenge_record_missing' | 'challenge_record_removed' | 'null', nullable, required
    - `records` object[], required: The records to add, each with what public DNS shows. A zone apex also lists its www companion (_acme-challenge.www and www), which redirects to the apex.
      - `type` 'CNAME' | 'A', required
      - `name` string, required: Fully qualified record name
      - `host` string, nullable, required: Record name relative to the domain DNS zone (@ for the zone itself); null until the zone is known
      - `value` string, nullable, required: Null only while custom domains are unavailable
      - `purpose` 'verification' | 'traffic', required
      - `state` 'ok' | 'waiting' | 'elsewhere', required: elsewhere: a traffic record that resolves to an address other than the edge
      - `observed` string[]
      - `aliasValue` string: For an A record: the hostname an ALIAS, ANAME or flattened CNAME may point to instead
      - `acceptedValue` string: For the www record of a zone apex: the apex, which the CNAME may point to instead
    - `zone` string, nullable, required: The DNS zone the domain lives in, once public DNS shows it
    - `dnsTargetState` 'unknown' | 'ok' | 'elsewhere' | 'missing', required
    - `certificateState` 'waiting' | 'issuing' | 'issued', required
    - `www` object, nullable, required: A zone apex only: its www companion, which redirects to the apex while the apex certificate covers it. requested: being added to the certificate; issued: covered; failing: covered but not renewing; failed: not covered within 24 hours, so it was removed and the apex renews alone.
      - `name` string, required
      - `certificateState` 'none' | 'requested' | 'issued' | 'failing' | 'failed', required
    - `converging` boolean, required: The domain will change state without anyone acting (pending or issuing)
    - `checkedAt` string, date-time, nullable, required
    - `activeAt` string, date-time, nullable, required
    - `createdAt` string, date-time, required

## Other responses

- `400`: organizationId missing (organization-id-required), not a public domain name (project-domain-invalid), a Eurobase address (project-domain-platform-zone) or an invalid projectId (project-domain-target-invalid)
- `403`: Only the workspace owner can manage its domains (workspace-domain-owner-required)
- `409`: Already in the workspace (project-domain-exists), domain limit reached (project-domain-limit-reached) or a project outside the workspace (project-domain-workspace-mismatch)
- `429`: Too many domains connected by this user today
- `503`: Custom domains are not available (project-domains-not-configured)

---

[API](https://skmtc.dev/eurobase/apis/eurobase-api.md) · [All operations](https://skmtc.dev/eurobase/apis/eurobase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/eurobase/apis/eurobase-api/revisions/5266a299d18a?raw)