> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Custom Domain

> Read the current custom domain state for an app.

Returns the current custom domain state for an app, including the configured hosts, status, required action, and the DNS records to add. See [Custom Domain](/guides/concepts/custom-domain) for the concept and lifecycle.

<Note>
  This endpoint is **read-only**. It returns the stored state but does **not** trigger verification or advance the status. To re-check DNS/SSL and move the status forward, call [Verify Custom Domain](/api-reference/workspace/verify-custom-domain).
</Note>

## Request

<ParamField header="Authorization" type="string" required>
  `Bearer <API_KEY>` from Console > Developers > Workspace API Keys.
</ParamField>

### Path parameters

<ParamField path="client_id" type="string" required>
  Client identifier of the app.
</ParamField>

## Response

Returns a `CustomDomainStateDto`.

<ResponseField name="webDomain" type="string">
  The configured Web Frontend host (serves the hosted verification UI). Omitted when unconfigured.
</ResponseField>

<ResponseField name="oidcDomain" type="string">
  The configured OIDC Backend host (serves the OIDC endpoints). Omitted when unconfigured.
</ResponseField>

<ResponseField name="status" type="string">
  Lifecycle status. One of `unconfigured`, `awaiting_dns`, `verifying`, `active`, `invalid`. See [Custom Domain](/guides/concepts/custom-domain) for the lifecycle.
</ResponseField>

<ResponseField name="requiredAction" type="string">
  What you need to do next. One of `none`, `add_cname`, `waiting`, `verify`, `contact_support`, `retry`.
</ResponseField>

<ResponseField name="statusMessage" type="string">
  Human-readable explanation of the current status. Omitted when there is nothing to report.
</ResponseField>

<ResponseField name="dnsRecords" type="object[]">
  DNS records to add at your DNS provider. Add **every** required record for **both** hosts before verifying.

  <Expandable title="record">
    <ResponseField name="id" type="string">
      Stable identifier for the record.
    </ResponseField>

    <ResponseField name="type" type="string">
      DNS record type (for example, `CNAME` or `TXT`).
    </ResponseField>

    <ResponseField name="host" type="string">
      The custom host this record belongs to.
    </ResponseField>

    <ResponseField name="name" type="string">
      The record name to create at your DNS provider.
    </ResponseField>

    <ResponseField name="value" type="string">
      The record value.
    </ResponseField>

    <ResponseField name="required" type="boolean">
      Whether the record is required for the domain to go active.
    </ResponseField>

    <ResponseField name="description" type="string">
      What the record is for. Omitted when not applicable.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="lastCheckedAt" type="string">
  ISO 8601 timestamp of the most recent verify. Omitted until the first verify runs.
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -H "Authorization: Bearer sk_workspace_test_..." \
    "https://sandbox.api.hopae.com/connect/v1/apps/abc123/custom-domain"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "webDomain": "verify.example.com",
    "oidcDomain": "connect.example.com",
    "status": "awaiting_dns",
    "requiredAction": "add_cname",
    "statusMessage": "Add the DNS records below, then verify.",
    "dnsRecords": [
      {
        "id": "web-cname",
        "type": "CNAME",
        "host": "verify.example.com",
        "name": "verify.example.com",
        "value": "cname.hopae-edge.com",
        "required": true,
        "description": "Routes your Web Frontend host to the Hopae edge."
      },
      {
        "id": "oidc-cname",
        "type": "CNAME",
        "host": "connect.example.com",
        "name": "connect.example.com",
        "value": "cname.hopae-edge.com",
        "required": true,
        "description": "Routes your OIDC Backend host to the Hopae edge."
      },
      {
        "id": "web-ownership",
        "type": "TXT",
        "host": "verify.example.com",
        "name": "_hopae-verify.verify.example.com",
        "value": "hopae-domain-verification=2b9f8e1c4a7d",
        "required": true,
        "description": "Proves you control the domain."
      },
      {
        "id": "web-dcv",
        "type": "CNAME",
        "host": "verify.example.com",
        "name": "_acme-challenge.verify.example.com",
        "value": "verify.example.com.5f2a9c.dcv.hopae.com",
        "required": true,
        "description": "Domain Control Validation for SSL certificate issuance."
      },
      {
        "id": "oidc-dcv",
        "type": "CNAME",
        "host": "connect.example.com",
        "name": "_acme-challenge.connect.example.com",
        "value": "connect.example.com.8d1b3e.dcv.hopae.com",
        "required": true,
        "description": "Domain Control Validation for SSL certificate issuance."
      }
    ],
    "lastCheckedAt": "2026-06-18T01:12:48.000Z"
  }
  ```
</ResponseExample>