Configure Custom Domain

curl -X PUT \
  -H "Authorization: Bearer sk_workspace_test_..." \
  -H "Content-Type: application/json" \
  -d '{"webDomain":"verify.example.com","oidcDomain":"connect.example.com"}' \
  "https://sandbox.api.hopae.com/connect/v1/apps/abc123/custom-domain"

{
  "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."
    }
  ]
}

PUT

apps

{client_id}

custom-domain

curl -X PUT \
  -H "Authorization: Bearer sk_workspace_test_..." \
  -H "Content-Type: application/json" \
  -d '{"webDomain":"verify.example.com","oidcDomain":"connect.example.com"}' \
  "https://sandbox.api.hopae.com/connect/v1/apps/abc123/custom-domain"

{
  "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."
    }
  ]
}

Sets the two custom hosts and starts provisioning. Returns the CustomDomainStateDto, including the DNS records to add. See Custom Domain for the concept and lifecycle.

This configures one custom domain per app. If a custom domain is already configured, this returns 400 — the error message includes the current status. To change it, delete the existing one first, then configure again.

Request

string

required

Bearer <API_KEY> from Console > Developers > Workspace API Keys.

string

application/json

Path parameters

string

required

Client identifier of the app.

Request body

string

required

The Web Frontend host (serves the hosted verification UI), e.g. verify.example.com. Host only — no scheme or path.

string

required

The OIDC Backend host (serves the OIDC endpoints), e.g. connect.example.com. Host only — no scheme or path.

Response

Returns the updated CustomDomainStateDto. After a successful configure, the status moves to awaiting_dns and the response carries the DNS records to add.

string

The configured Web Frontend host.

string

The configured OIDC Backend host.

string

Lifecycle status. One of unconfigured, awaiting_dns, verifying, active, invalid.

string

What you need to do next. One of none, add_cname, waiting, verify, contact_support, retry.

string

Human-readable explanation of the current status. Omitted when there is nothing to report.

object[]

DNS records to add at your DNS provider. See Get Custom Domain for each record’s fields.

string

ISO 8601 timestamp of the most recent verify. Omitted until the first verify runs.

Validation: both hosts are host-only (no https://, no path). They must differ from each other and must share the same base domain (for example, both under example.com).

Configuring only generates the records — it does not verify them. Add all returned DNS records, then call Verify Custom Domain to advance the status.

curl -X PUT \
  -H "Authorization: Bearer sk_workspace_test_..." \
  -H "Content-Type: application/json" \
  -d '{"webDomain":"verify.example.com","oidcDomain":"connect.example.com"}' \
  "https://sandbox.api.hopae.com/connect/v1/apps/abc123/custom-domain"

{
  "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."
    }
  ]
}

Overview

Workspace

Apps

Providers

Provider Activation

Redirect URIs

Webhooks

Custom Domain

Workflows

Production Tests

Configure Custom Domain

Request

Path parameters

Request body

Response

​Request

​Path parameters

​Request body

​Response

Request

Path parameters

Request body

Response